當地語系化元素

2025-05-08

這很重要

自 2025 年 5 月 1 日起，Azure AD B2C 將不再可供新客戶購買。在我們的常見問題中深入瞭解。

備註

在 Azure Active Directory B2C 中，自定義原則的設計主要是為了解決複雜的案例。在大部分情況下，我們建議您使用內建的使用者流程。如果您尚未這麼做，請了解開始使用 Active Directory B2C 中的自定義原則入門套件。

的 Localization 元素允許您在使用者旅程的策略中支援多個區域設置或語言。原則中的本地化支援允許您：

在策略中設置受支援語言的顯式清單，並選擇預設語言。
提供特定於語言的字串和集合。

<Localization Enabled="true">
  <SupportedLanguages DefaultLanguage="en" MergeBehavior="ReplaceAll">
    <SupportedLanguage>en</SupportedLanguage>
    <SupportedLanguage>es</SupportedLanguage>
  </SupportedLanguages>
  <LocalizedResources Id="api.localaccountsignup.en">
  <LocalizedResources Id="api.localaccountsignup.es">
  ...

Localization 元素包含以下屬性：

屬性	為必填項目	說明
已啟用	否	可能的值： `true` 或 `false`。

Localization 元素包含以下 XML 元素

元素	發生次數	說明
支援的語言	1：n	支援的語言清單。
LocalizedResources	0：n	當地語系化資源清單。

支援的語言

SupportedLanguages 元素包含以下屬性：

屬性	為必填項目	說明
預設語言	是的	要用作當地語系化資源的預設語言。
MergeBehavior	否	與父策略中存在的具有相同標識碼的任何 ClaimType 合併在一起的值的枚舉值。當您覆蓋基本策略中指定的聲明時，請使用此屬性。可能的值：`Append`、`Prepend` 或 `ReplaceAll`。該值 `Append` 指定存在的數據集合應附加到父策略中指定的集合的末尾。該值 `Prepend` 指定存在的數據集合應添加到父策略中指定的集合之前。該值 `ReplaceAll` 指定應忽略父策略中定義的數據集合，而是使用當前策略中定義的數據。

支援的語言

SupportedLanguages 元素包含以下元素：

元素	發生次數	說明
支援的語言	1：n	顯示符合 RFC 5646 - 用於標識語言的標記的語言標記的內容。

LocalizedResources

LocalizedResources 元素包含以下屬性：

屬性	為必填項目	說明
身份識別碼	是的	用於唯一標識當地語系化資源的標識碼。

LocalizedResources 元素包含以下元素：

元素	發生次數	說明
LocalizedCollections	0：n	定義各種區域性中的整個集合。對於各種區域性，集合可以具有不同數量的項和不同的字串。集合的範例包括聲明類型中顯示的枚舉。例如，國家/地區清單在下拉清單中向用戶顯示。
LocalizedStrings 的	0：n	定義各種區域性中除集合中出現的字串之外的所有字串。

LocalizedCollections

LocalizedCollections 元素包含以下元素：

元素	發生次數	說明
LocalizedCollection	1：n	支援的語言清單。

LocalizedCollection

LocalizedCollection 元素包含以下屬性：

屬性	為必填項目	說明
元素類型	是的	引用策略檔中的 ClaimType 元素或使用者介面元素。
元素ID	是的	一個字串，其中包含對 ClaimsSchema 節中定義的聲明類型的引用，如果 ElementType 設置為 ClaimType，則使用該聲明類型。
目標集合	是的	目標集合。

LocalizedCollection 元素包含以下元素：

元素	發生次數	說明
項目	0：n	定義一個可用選項，供使用者在用戶介面中為聲明選擇，例如下拉清單中的值。

Item 元素包含以下屬性：

屬性	為必填項目	說明
文字	是的	應在此選項的使用者介面中向用戶顯示的使用者友好型顯示字串。
價值觀	是的	與選擇此選項關聯的字串 claim 值。
SelectByDefault	否	指出是否應該在UI中預設選取此選項。可能的值：True 或 False。

下面的示例演示 LocalizedCollections 元素的用法。它包含兩個 LocalizedCollection 元素，一個用於英語，另一個用於西班牙文。兩者都使用英語和西班牙文的專案清單設置聲明的 Gender 集合。如需更多範例，請參閱宣告限制列舉實時示範。

<LocalizedResources Id="api.selfasserted.en">
  <LocalizedCollections>
    <LocalizedCollection ElementType="ClaimType" ElementId="Gender" TargetCollection="Restriction">
      <Item Text="Female" Value="F" />
      <Item Text="Male" Value="M" />
    </LocalizedCollection>
  </LocalizedCollections>
</LocalizedResources>

<LocalizedResources Id="api.selfasserted.es">
 <LocalizedCollections>
   <LocalizedCollection ElementType="ClaimType" ElementId="Gender" TargetCollection="Restriction">
      <Item Text="Femenino" Value="F" />
      <Item Text="Masculino" Value="M" />
    </LocalizedCollection>
  </LocalizedCollections>
</LocalizedResources>

LocalizedStrings 的

LocalizedStrings 元素包含以下元素：

元素	發生次數	說明
LocalizedString	1：n	當地語系化字串。

LocalizedString 元素包含以下屬性：

屬性	為必填項目	說明
元素類型	是的	可能的值：ClaimsProvider、ClaimType、ErrorMessage、GetLocalizedStringsTransformationClaimType、FormatLocalizedStringTransformationClaimType、Predicate 、PredicateValidation 或 UxElement。
元素ID	是的	如果 ElementType 設定為 `ClaimType`、 `Predicate`、或 `PredicateValidation`，則此元素包含對 ClaimsSchema 節中已定義的聲明類型的引用。
字串ID	是的	如果 ElementType 設定為 `ClaimType`，則此元素包含對聲明類型的屬性的引用。可能的值：`DisplayName`、`AdminHelpText` 或 `PatternHelpText`。該值 `DisplayName` 用於設置聲明顯示名稱。該值 `AdminHelpText` 用於設置聲明用戶的説明文本名稱。該值 `PatternHelpText` 用於設置聲明模式説明文本。如果 ElementType 設定為 `UxElement`，則此元素包含對使用者介面元素屬性的引用。如果 ElementType 設定為 `ErrorMessage`，則此元素指定錯誤訊息的標識碼。有關標識碼的完整清單，請參閱`UxElement`。

元素類型

對要本地化的策略中的聲明類型、聲明轉換或使用者介面元素的 ElementType 引用。

要本地化的元素	元素類型	元素ID	字串ID
身份供應商名稱	`ClaimsProvider`		ClaimsExchange 元素的 ID
聲明類型屬性	`ClaimType`	索賠類型的名稱	要本地化的聲明的屬性。可能的值： `AdminHelpText`、 `DisplayName`、 `PatternHelpText`和 `UserHelpText`。
錯誤訊息	`ErrorMessage`		錯誤訊息的ID
將本地化字串複製到聲明中	`GetLocalizedStringsTransformationClaimType`		輸出聲明的名稱
謂詞使用者消息	`Predicate`	謂詞的名稱	要本地化的謂詞的屬性。可能的值： `HelpText`.
謂片語使用者消息	`PredicateValidation`	PredicateValidation 元素的 ID。	PredicateGroup 元素的 ID。謂片語必須是 ElementId 中定義的謂詞驗證元素的子元素。
使用者介面元素	`UxElement`		要本地化的使用者介面元素的ID。
顯示控制件	`DisplayControl`	顯示控制件的ID。	要本地化的使用者介面元素的ID。

範例

ClaimsProvider

ClaimsProvider 值用於當地語系化其中一個聲明提供程式顯示名稱。

<OrchestrationStep Order="2" Type="ClaimsExchange">
  ...
  <ClaimsExchanges>
    <ClaimsExchange Id="FacebookExchange" TechnicalProfileReferenceId="Facebook-OAUTH" />
    <ClaimsExchange Id="GoogleExchange" TechnicalProfileReferenceId="Google-OAUTH" />
    <ClaimsExchange Id="LinkedInExchange" TechnicalProfileReferenceId="LinkedIn-OAUTH" />
  </ClaimsExchanges>
</OrchestrationStep>

以下範例演示如何當地語系化聲明提供程式的顯示名稱。

<LocalizedString ElementType="ClaimsProvider" StringId="FacebookExchange">Facebook</LocalizedString>
<LocalizedString ElementType="ClaimsProvider" StringId="GoogleExchange">Google</LocalizedString>
<LocalizedString ElementType="ClaimsProvider" StringId="LinkedInExchange">LinkedIn</LocalizedString>

ClaimType

ClaimType 值用於當地語系化其中一個聲明屬性。

<ClaimType Id="email">
  <DisplayName>Email Address</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Email address that can be used to contact you.</UserHelpText>
  <UserInputType>TextBox</UserInputType>
</ClaimType>

以下示例演示如何當地語系化電子郵件聲明類型的 DisplayName、UserHelpText 和 PatternHelpText 屬性。

<LocalizedString ElementType="ClaimType" ElementId="email" StringId="DisplayName">Email</LocalizedString>
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="UserHelpText">Please enter your email</LocalizedString>
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="PatternHelpText">Please enter a valid email address</LocalizedString>

錯誤訊息

ErrorMessage 值用於當地語系化其中一條系統錯誤消息。

<TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">true</Item>
    <Item Key="UserMessageIfClaimsPrincipalAlreadyExists">You are already registered, please press the back button and sign in instead.</Item>
  </Metadata>
  ...
</TechnicalProfile>

下面的示例演示如何當地語系化 UserMessageIfClaimsPrincipalAlreadyExists 錯誤消息。

<LocalizedString ElementType="ErrorMessage" StringId="UserMessageIfClaimsPrincipalAlreadyExists">The account you are trying to create already exists, please sign-in.</LocalizedString>

格式LocalizedStringTransformationClaimType

FormatLocalizedStringTransformationClaimType 值用於將聲明格式化為當地語系化字串。有關更多資訊，請參閱 FormatLocalizedString 聲明轉換

<ClaimsTransformation Id="SetResponseMessageForEmailAlreadyExists" TransformationMethod="FormatLocalizedString">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="email" />
  </InputClaims>
  <InputParameters>
    <InputParameter Id="stringFormatId" DataType="string" Value="ResponseMessage_EmailExists" />
  </InputParameters>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="responseMsg" TransformationClaimType="outputClaim" />
  </OutputClaims>
</ClaimsTransformation>

以下示例演示如何當地語系化 FormatLocalizedStringTransformationClaimType 聲明轉換的字串格式。

<LocalizedString ElementType="FormatLocalizedStringTransformationClaimType" StringId="ResponseMessage_EmailExists">The email '{0}' is already an account in this organization. Click Next to sign in with that account.</LocalizedString>

GetLocalizedStringsTransformationClaimType

GetLocalizedStringsTransformationClaimType 值用於將當地語系化字串複製到聲明中。有關更多資訊，請參閱 GetLocalizedStringsTransformation 聲明轉換

<ClaimsTransformation Id="GetLocalizedStringsForEmail" TransformationMethod="GetLocalizedStringsTransformation">
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="subject" TransformationClaimType="email_subject" />
    <OutputClaim ClaimTypeReferenceId="message" TransformationClaimType="email_message" />
    <OutputClaim ClaimTypeReferenceId="codeIntro" TransformationClaimType="email_code" />
    <OutputClaim ClaimTypeReferenceId="signature" TransformationClaimType="email_signature" />
   </OutputClaims>
</ClaimsTransformation>

下面的示例演示如何當地語系化 GetLocalizedStringsTransformation 聲明轉換的輸出聲明。

<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_subject">Contoso account email verification code</LocalizedString>
<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_message">Thanks for verifying your account!</LocalizedString>
<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_code">Your code is</LocalizedString>
<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_signature">Sincerely</LocalizedString>

謂語

Predicate 值用於當地語系化其中一個 Predicate 錯誤消息。

<Predicates>
  <Predicate Id="LengthRange" Method="IsLengthRange"  HelpText="The password must be between 6 and 64 characters.">
    <Parameters>
      <Parameter Id="Minimum">6</Parameter>
      <Parameter Id="Maximum">64</Parameter>
    </Parameters>
  </Predicate>
  <Predicate Id="Lowercase" Method="IncludesCharacters" HelpText="a lowercase letter">
    <Parameters>
      <Parameter Id="CharacterSet">a-z</Parameter>
    </Parameters>
  </Predicate>
  <Predicate Id="Uppercase" Method="IncludesCharacters" HelpText="an uppercase letter">
    <Parameters>
      <Parameter Id="CharacterSet">A-Z</Parameter>
    </Parameters>
  </Predicate>
</Predicates>

以下示例演示如何當地語系化謂詞説明文本。

<LocalizedString ElementType="Predicate" ElementId="LengthRange" StringId="HelpText">The password must be between 6 and 64 characters.</LocalizedString>
<LocalizedString ElementType="Predicate" ElementId="Lowercase" StringId="HelpText">a lowercase letter</LocalizedString>
<LocalizedString ElementType="Predicate" ElementId="Uppercase" StringId="HelpText">an uppercase letter</LocalizedString>

PredicateValidation

PredicateValidation 值用於當地語系化 PredicateValidation 組錯誤消息之一。

<PredicateValidations>
  <PredicateValidation Id="CustomPassword">
    <PredicateGroups>
      <PredicateGroup Id="LengthGroup">
        <PredicateReferences MatchAtLeast="1">
          <PredicateReference Id="LengthRange" />
        </PredicateReferences>
      </PredicateGroup>
      <PredicateGroup Id="CharacterClasses">
        <UserHelpText>The password must have at least 3 of the following:</UserHelpText>
        <PredicateReferences MatchAtLeast="3">
          <PredicateReference Id="Lowercase" />
          <PredicateReference Id="Uppercase" />
          <PredicateReference Id="Number" />
          <PredicateReference Id="Symbol" />
        </PredicateReferences>
      </PredicateGroup>
    </PredicateGroups>
  </PredicateValidation>
</PredicateValidations>

以下示例顯示如何當地語系化謂詞驗證組説明文本。

<LocalizedString ElementType="PredicateValidation" ElementId="CustomPassword" StringId="CharacterClasses">The password must have at least 3 of the following:</LocalizedString>

UxElement （烏克元素）

UxElement 值用於當地語系化其中一個使用者介面元素。以下示例說明如何當地語系化 continue 和 cancel 按鈕。

<LocalizedString ElementType="UxElement" StringId="button_continue">Create new account</LocalizedString>
<LocalizedString ElementType="UxElement" StringId="button_cancel">Cancel</LocalizedString>

顯示控制

DisplayControl 值用於當地語系化其中一個顯示 Control 使用者介面元素。啟用后，顯示控件localizedStrings 優先於某些 UxElement StringID，如 ver_but_send、 ver_but_edit、 ver_but_resend 和 ver_but_verify。以下示例顯示如何當地語系化 send 和 verify 按鈕。

<LocalizedString ElementType="DisplayControl" ElementId="emailVerificationControl" StringId="but_send_code">Send verification code</LocalizedString>
<LocalizedString ElementType="DisplayControl" ElementId="emailVerificationControl" StringId="but_verify_code">Verify code</LocalizedString>

在自斷言技術配置檔的 Metadata 部分中，引用的 ContentDefinition 需要將 DataUri 設置為頁面佈局版本 2.1.0 或更高版本。例如：

<ContentDefinition Id="api.selfasserted">
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:2.1.0</DataUri>
  ...

後續步驟

如需本地化範例，請參閱下列文章：

共用方式為

當地語系化元素

支援的語言

支援的語言

LocalizedResources

LocalizedCollections

LocalizedCollection

LocalizedStrings 的

元素類型

範例

ClaimsProvider

ClaimType

錯誤訊息

格式LocalizedStringTransformationClaimType

GetLocalizedStringsTransformationClaimType

謂語

PredicateValidation

UxElement （烏克元素）

顯示控制

後續步驟

意見反應

其他資源