Localization 元素

文章
01/11/2024

注意

在 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 元素包含下列屬性：

屬性	必要	描述
啟用	No	可能的值：`true` 或 `false`。

Localization 元素包含下列 XML 元素

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

SupportedLanguages

SupportedLanguages 元素包含下列屬性：

屬性	必要	描述
DefaultLanguage	Yes	用來做為當地語系化資源的預設語言。
MergeBehavior	No	列舉值，這些值是與具有相同識別碼之父代原則中存在的 ClaimType 合併的值。在覆寫基本原則中指定的宣告時，請使用這個屬性。可能的值：`Append`、`Prepend` 或 `ReplaceAll`。 `Append` 值指定應該在父代原則中指定的集合結尾後，附加上存在的資料集合。 `Prepend` 值指定應該在父代原則中指定的集合之前，新增存在的資料集合。 `ReplaceAll` 值指定應該忽略父代原則中定義的資料集合，而改用目前原則中定義的資料。

SupportedLanguages

SupportedLanguages 元素包含下列元素：

元素	發生次數	Description
SupportedLanguage	1:n	根據 RFC 5646 顯示符合語言標記的內容 - 識別語言的標記。

LocalizedResources

LocalizedResources 元素包含下列屬性：

屬性	必要	描述
識別碼	Yes	用來唯一識別當地語系化資源的識別碼。

LocalizedResources 元素包含下列元素：

元素	發生次數	Description
LocalizedCollections	0:n	定義不同文化中的整個集合。對於不同的文化特性，集合可以有不同數量的項目和不同的字串。集合範例會包含宣告類型中出現的列舉。例如在下拉式清單中，會向使用者顯示國家/地區清單。
LocalizedStrings	0:n	定義各種文化特性中的所有字串，出現在集合中的字串除外。

LocalizedCollections

LocalizedCollections 元素包含下列元素：

元素	發生次數	Description
LocalizedCollection	1:n	支援語言清單。

LocalizedCollection

LocalizedCollection 元素包含下列屬性：

屬性	必要	描述
ElementType	Yes	參考原則檔中的 ClaimType 元素或使用者介面元素。
ElementId	Yes	此字串包含對 ClaimsSchema 區段中已定義的宣告類型，如果 ElementType 設為 ClaimType，則會使用該字串。
TargetCollection	Yes	目標集合。

LocalizedCollection 元素包含下列元素：

元素	發生次數	描述
Item	0:n	定義在使用者介面中可供使用者選取的某個宣告選項，例如下拉式清單中的值。

Item 元素包含下列屬性：

屬性	必要	描述
Text	Yes	此選項應會在使用者介面中向使用者顯示的易記顯示字串。
值	Yes	與選取此選項相關聯的字串宣告值。
SelectByDefault	No	指出預設是否應該在 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 元素包含下列元素：

元素	發生次數	Description
LocalizedString	1:n	當地語系化的字串。

LocalizedString 元素包含下列屬性：

屬性	必要	描述
ElementType	Yes	可能的值：ClaimsProvider、ClaimType、ErrorMessage、GetLocalizedStringsTransformationClaimType、FormatLocalizedStringTransformationClaimType、Predicate、PredicateValidation 或 UxElement。
ElementId	Yes	如果 ElementType 設為 `ClaimTypePredicate` 或 `PredicateValidation`，則此元素會包含對 ClaimsSchema 區段中已定義之宣告類型的參考。
StringId	Yes	如果 ElementType 設為 `ClaimType`，則此元素會包含對宣告類型之屬性的參考。可能的值：`DisplayName`、`AdminHelpText` 或 `PatternHelpText`。 `DisplayName` 值用於設定宣告顯示名稱。 `AdminHelpText` 值用於設定宣告使用者的說明文字名稱。 `PatternHelpText` 值用於設定宣告模式說明文字。如果 ElementType 設為 `UxElement`，則此元素會包含使用者介面元素之屬性的參考。如果 ElementType 設為 `ErrorMessage`，則此元素會指定錯誤訊息的識別碼。如需 `UxElement` 識別碼的完整清單，請參閱當地語系化字串識別碼。

ElementType

ElementType 會參考原則中要當地語系化的宣告類型、宣告轉換或使用者介面元素。

要當地語系化的元素	ElementType	ElementId	StringId
識別提供者名稱	`ClaimsProvider`		ClaimsExchange 元素的識別碼
宣告類型屬性	`ClaimType`	宣告類型的名稱	要當地語系化之宣告的屬性。可能的值：`AdminHelpText`、`DisplayName`、`PatternHelpText` 和 `UserHelpText`。
錯誤訊息	`ErrorMessage`		錯誤訊息的識別碼
將當地語系化的字串複製到宣告中	`GetLocalizedStringsTra nsformationClaimType`		輸出宣告的名稱
述詞使用者訊息	`Predicate`	述詞的名稱	要當地語系化之述詞的屬性。可能的值：`HelpText`。
述詞群組使用者訊息	`PredicateValidation`	PredicateValidation 元素的識別碼。	PredicateGroup 元素的識別碼。述詞群組必須是述詞驗證元素的子系，如 ElementId 中所定義。
使用者介面元素	`UxElement`		要當地語系化之使用者介面元素的識別碼。
顯示控制項	`DisplayControl`	顯示控制項的識別碼。	要當地語系化之使用者介面元素的識別碼。

範例

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

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>

FormatLocalizedStringTransformationClaimType

FormatLocalizedStringTransformationClaimType 值會用來將宣告格式化為已當地語系化的字串。如需詳細資訊，請參閱 FormatLocalizedString 宣告轉換

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

下列範例示範如何將 FormatLocalizedStringTransformationClaimType 宣告轉換的字串格式當地語系化。

<LocalizedString ElementType="FormatLocalizedStringTransformationClaimType" StringId="ResponseMessge_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 值會用來將其中一個 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 值會用來將其中一個使用者介面元素當地語系化。下列範例示範如何將 [繼續] 和 [取消] 按鈕當地語系化。

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

DisplayControl

DisplayControl 值會用來將其中一個顯示控制項使用者介面元素當地語系化。啟用時，顯示控制項 localizedStrings 的「優先順序」會高於某些 UxElement StringID，例如 ver_but_send、ver_but_edit、ver_but_resend 和 ver_but_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>

在自我判斷技術設定檔的中繼資料區段中，參考的 ContentDefinition 必須將 DataUri 設定為頁面配置版本 2.1.0 或更高版本。例如：

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

後續步驟

請參閱下列文章以取得當地語系化範例：

分享方式：

Localization 元素

SupportedLanguages

SupportedLanguages

LocalizedResources

LocalizedCollections

LocalizedCollection

LocalizedStrings

ElementType

範例

ClaimsProvider

ClaimType

ErrorMessage

FormatLocalizedStringTransformationClaimType

GetLocalizedStringsTransformationClaimType

Predicate

PredicateValidation

UxElement

DisplayControl

後續步驟

更多資源