本地化元素Localization element

备注

在 Azure Active Directory B2C 中,custom policies 主要用于解决复杂方案。In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. 大多数情况下,建议使用内置的用户流For most scenarios, we recommend that you use built-in user flows.

使用 Localization 元素可在用户旅程的策略中支持多个区域设置或语言。The Localization element allows you to support multiple locales or languages in the policy for the user journeys. 使用策略中的本地化支持可以:The localization support in policies allows you to:

  • 在策略中设置支持的语言的显式列表和选择默认语言。Set up the explicit list of the supported languages in a policy and pick a default language.
  • 提供特定于语言的字符串和集合。Provide language-specific strings and collections.
<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 元素包含以下属性:The Localization element contains the following attributes:

属性Attribute 必须Required 说明Description
EnabledEnabled No 可能的值:truefalsePossible values: true or false.

Localization 元素包含以下 XML 元素The Localization element contains following XML elements

元素Element 出现次数Occurrences 说明Description
SupportedLanguagesSupportedLanguages 1:n1:n 支持的语言列表。List of supported languages.
LocalizedResourcesLocalizedResources 0:n0:n 本地化资源列表。List of localized resources.

SupportedLanguagesSupportedLanguages

SupportedLanguages 元素包含以下属性:The SupportedLanguages element contains the following attributes:

属性Attribute 必须Required 说明Description
DefaultLanguageDefaultLanguage Yes 用作本地化资源默认值的语言。The language to be used as the default for localized resources.
MergeBehaviorMergeBehavior No 与父策略中具有相同标识符的任何 ClaimType 合并在一起的值的枚举值。An enumeration values of values that are merged together with any ClaimType present in a parent policy with the same identifier. 覆盖基本策略中指定的声明时,请使用此属性。Use this attribute when you overwrite a claim specified in base policy. 可能的值:AppendPrependReplaceAllPossible values: Append, Prepend, or ReplaceAll. Append 值指定应将现有数据集合追加到父策略中指定的集合的末尾。The Append value specifies that the collection of data present should be appended to the end of the collection specified in the parent policy. Prepend 值指定应将现有数据集合添加到父策略中指定的集合的前面。The Prepend value specifies that the collection of data present should be added before the collection specified in the parent policy. ReplaceAll 值指定应忽略父策略中定义的数据集合,改用当前策略中定义的数据。The ReplaceAll value specifies that the collection of data defined in the parent policy should be ignored, using instead the data defined in the current policy.

SupportedLanguagesSupportedLanguages

SupportedLanguages 元素包含以下元素:The SupportedLanguages element contains the following elements:

元素Element 出现次数Occurrences 说明Description
SupportedLanguageSupportedLanguage 1:n1:n 显示符合 RFC 5646“用于标识语言的标记”中所述语言标记的内容。Displays content that conforms to a language tag per RFC 5646 - Tags for Identifying Languages.

LocalizedResourcesLocalizedResources

LocalizedResources 元素包含以下属性:The LocalizedResources element contains the following attributes:

属性Attribute 必须Required 说明Description
IDId Yes 用于唯一标识本地化资源的标识符。An identifier that is used to uniquely identify localized resources.

LocalizedResources 元素包含以下元素:The LocalizedResources element contains the following elements:

元素Element 出现次数Occurrences 说明Description
LocalizedCollectionsLocalizedCollections 0:n0:n 在各种区域性中定义整个集合。Defines entire collections in various cultures. 一个集合可以包含不同的项数,以及适用于各种区域性的不同字符串。A collection can have different number of items and different strings for various cultures. 集合的示例包括声明类型中显示的枚举。Examples of collections include the enumerations that appear in claim types. 例如,在下拉列表中向用户显示国家/地区列表。For example, a country/region list is shown to the user in a drop-down list.
LocalizedStringsLocalizedStrings 0:n0:n 在各种区域性中定义所有字符串,但集合中出现的字符串除外。Defines all of the strings, except those strings that appear in collections, in various cultures.

LocalizedCollectionsLocalizedCollections

LocalizedCollections 元素包含以下元素:The LocalizedCollections element contains the following elements:

元素Element 出现次数Occurrences 说明Description
LocalizedCollectionLocalizedCollection 1:n1:n 支持的语言列表。List of supported languages.

LocalizedCollectionLocalizedCollection

LocalizedCollection 元素包含以下属性:The LocalizedCollection element contains the following attributes:

属性Attribute 必须Required 说明Description
ElementTypeElementType Yes 引用策略文件中的 ClaimType 元素或用户界面元素。References a ClaimType element or a user interface element in the policy file.
ElementIdElementId Yes 一个字符串,包含当 ElementType 设置为 ClaimType 时使用的 ClaimsSchema 节中已定义的声明类型的引用。A string that contains a reference to a claim type already defined in the ClaimsSchema section that is used if ElementType is set to a ClaimType.
TargetCollectionTargetCollection Yes 目标集合。The target collection.

LocalizedCollection 元素包含以下元素:The LocalizedCollection element contains the following elements:

元素Element 出现次数Occurrences 说明Description
项目Item 0:n0:n 定义可让用户在用户界面中为声明选择的可用选项,例如下拉列表中的值。Defines an available option for the user to select for a claim in the user interface, such as a value in a dropdown.

Item 元素包含以下属性:The Item element contains the following attributes:

属性Attribute 必须Required 说明Description
文本Text Yes 应在用户界面中向用户显示的此选项的用户友好字符串。The user-friendly display string that should be shown to the user in the user interface for this option.
ValueValue Yes 与此选项关联的字符串声明值。The string claim value associated with selecting this option.
SelectByDefaultSelectByDefault No 指示默认情况下是否应在 UI 中选择此选项。Indicates whether or not this option should be selected by default in the UI. 可能的值:True 或 False。Possible values: True or False.

以下示例演示了 LocalizedCollections 元素的用法。The following example shows the use of the LocalizedCollections element. 其中包含两个 LocalizedCollection 元素,一个元素适用于英语区域设置,另一个元素适用于西班牙语区域设置。It contains two LocalizedCollection elements, one for English and another one for Spanish. 这两个元素都设置了声明 GenderRestriction 集合,以及适用于英语和西班牙语的项列表。Both set the Restriction collection of the claim Gender with a list of items for English and Spanish.

<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 Id="api.selfasserted.es">
 <LocalizedCollections>
   <LocalizedCollection ElementType="ClaimType" ElementId="Gender" TargetCollection="Restriction">
      <Item Text="Femenino" Value="F" />
      <Item Text="Masculino" Value="M" />
    </LocalizedCollection>
</LocalizedCollections>

LocalizedStringsLocalizedStrings

LocalizedStrings 元素包含以下元素:The LocalizedStrings element contains the following elements:

元素Element 出现次数Occurrences 说明Description
LocalizedStringLocalizedString 1:n1:n 一个本地化字符串。A localized string.

LocalizedString 元素包含以下属性:The LocalizedString element contains the following attributes:

属性Attribute 必须Required 说明Description
ElementTypeElementType Yes 可能的值:ClaimsProviderClaimTypeErrorMessageGetLocalizedStringsTransformationClaimTypePredicateInputValidationUxElementPossible values: ClaimsProvider, ClaimType, ErrorMessage, GetLocalizedStringsTransformationClaimType, Predicate, InputValidation, or UxElement.
ElementIdElementId Yes 如果 ElementType 设置为 ClaimTypePredicateInputValidation,此元素包含对 ClaimsSchema 节中已定义的声明类型的引用。If ElementType is set to ClaimType, Predicate, or InputValidation, this element contains a reference to a claim type already defined in the ClaimsSchema section.
StringIdStringId Yes 如果 ElementType 设置为 ClaimType,此元素包含对声明类型的属性的引用。If ElementType is set to ClaimType, this element contains a reference to an attribute of a claim type. 可能的值:DisplayNameAdminHelpTextPatternHelpTextPossible values: DisplayName, AdminHelpText, or PatternHelpText. DisplayName 值用于设置声明显示名称。The DisplayName value is used to set the claim display name. AdminHelpText 值用于设置声明用户的帮助文本名称。The AdminHelpText value is used to set the help text name of the claim user. PatternHelpText 值用于设置声明模式帮助文本。The PatternHelpText value is used to set the claim pattern help text. 如果 ElementType 设置为 UxElement,此元素包含对用户界面元素的属性的引用。If ElementType is set to UxElement, this element contains a reference to an attribute of a user interface element. 如果 ElementType 设置为 ErrorMessage,此元素指定错误消息的标识符。If ElementType is set to ErrorMessage, this element specifies the identifier of an error message. 有关 UxElement 标识符的完整列表,请参阅本地化字符串 IDSee Localization string IDs for a complete list of the UxElement identifiers.

ElementTypeElementType

ElementType 引用策略中要本地化的声明类型、声明转换或用户界面元素。The ElementType reference to a claim type, a claim transformation, or a user interface element in the policy to be localized.

要本地化的元素Element to localize ElementTypeElementType ElementIdElementId StringIdStringId
标识提供者名称Identity provider name ClaimsProvider ClaimsExchange 元素的 IDThe ID of the ClaimsExchange element
声明类型特性Claim type attributes ClaimType 声明类型的名称Name of the claim type 要本地化的声明的特性。The attribute of the claim to be localized. 可能的值:AdminHelpTextDisplayNamePatternHelpTextUserHelpTextPossible values: AdminHelpText, DisplayName, PatternHelpText, and UserHelpText.
错误消息Error message ErrorMessage 错误消息的 IDThe ID of the error message
将已本地化的字符串复制到声明中Copies localized strings into claims GetLocalizedStringsTra nsformationClaimType 输出声明的名称The name of the output claim
谓词用户消息Predicate user message Predicate 谓词的名称The name of the predicate 要本地化的谓词的特性。The attribute of the predicate to be localized. 可能的值:HelpTextPossible values: HelpText.
谓词组用户消息Predicate group user message InputValidation PredicateValidation 元素的 ID。The ID of the PredicateValidation element. PredicateGroup 元素的 ID。The ID of the PredicateGroup element. 谓词组必须是 ElementId 中定义的谓词验证元素的子级。The predicate group must be a child of the predicate validation element as defined in the ElementId.
用户界面元素User interface elements UxElement 要本地化的用户界面元素的 ID。The ID of the user interface element to be localized.
显示控件Display Control DisplayControl 显示控件的 ID。The ID of the display control. 要本地化的用户界面元素的 ID。The ID of the user interface element to be localized.

ClaimTypeClaimType

ClaimType 值用于本地化某个声明特性。The ClaimType value is used to localize one of the claim attributes.

<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 特性。The following example shows how to localize the DisplayName, UserHelpText, and PatternHelpText attributes of the email claim type.

<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>

ErrorMessageErrorMessage

ErrorMessage 值用于本地化某个系统错误消息。The ErrorMessage value is used to localize one of the system error messages.

<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 错误消息。The following example shows how to localize the UserMessageIfClaimsPrincipalAlreadyExists error message.

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

GetLocalizedStringsTransformationClaimTypeGetLocalizedStringsTransformationClaimType

GetLocalizedStringsTransformationClaimType 值用于将已本地化的字符串复制到声明中。The GetLocalizedStringsTransformationClaimType value is used to copy localized strings into claims. 有关详细信息,请参阅 GetLocalizedStringsTransformation 声明转换For more information, see GetLocalizedStringsTransformation claims transformation

<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 声明转换的输出声明。The following example shows how to localize output claims of the GetLocalizedStringsTransformation claims transformation.

<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>

PredicatePredicate

Predicate 值用于本地化某个 Predicate 错误消息。The Predicate value is used to localize one of the Predicate error messages.

<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>

以下示例演示如何本地化谓词帮助文本。The following example shows how to localize predicates help text.

<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>

InputValidationInputValidation

InputValidation 值用于本地化某个 PredicateValidation 组错误消息。The InputValidation value is used to localize one of the PredicateValidation group error messages.

<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>

以下示例演示如何本地化谓词验证组帮助文本。The following example shows how to localize a predicate validation group help text.

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

UxElementUxElement

UxElement 值用于本地化某个用户界面元素。The UxElement value is used to localize one of the user interface elements. 以下示例演示如何本地化继续和取消按钮。The following example shows how to localize the continue and cancel buttons.

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

DisplayControlDisplayControl

DisplayControl 值用于本地化某个显示控件用户界面元素。The DisplayControl value is used to localize one of the display Control user interface elements. 以下示例演示如何本地化发送和验证按钮。The following example shows how to localize the send and verify buttons.

<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 或更高版本。In the Metadata section of a self-asserted technical profile, the referenced ContentDefinition needs to have DataUri set to page layout version 2.1.0 or higher. 例如:For example:

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

后续步骤Next steps

有关本地化示例,请参阅以下文章:See the following articles for localization examples: