本地化元素

项目
02/07/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 元素包含以下属性：

属性	必须	说明
Enabled	否	可能的值：`true` 或 `false`。

Localization 元素包含以下 XML 元素

元素	出现次数	说明
SupportedLanguages	1:n	支持的语言列表。
LocalizedResources	0:n	本地化资源列表。

SupportedLanguages

SupportedLanguages 元素包含以下属性：

属性	必须	说明
DefaultLanguage	是	用作本地化资源默认值的语言。
MergeBehavior	否	与父策略中具有相同标识符的任何 ClaimType 合并在一起的值的枚举值。覆盖基本策略中指定的声明时，请使用此属性。可能的值：`Append`、`Prepend` 或 `ReplaceAll`。 `Append` 值指定应将现有数据集合追加到父策略中指定的集合的末尾。 `Prepend` 值指定应将现有数据集合添加到父策略中指定的集合的前面。 `ReplaceAll` 值指定应忽略父策略中定义的数据集合，改用当前策略中定义的数据。

SupportedLanguages

SupportedLanguages 元素包含以下元素：

元素	出现次数	说明
SupportedLanguage	1:n	显示符合 RFC 5646“用于标识语言的标记”中所述语言标记的内容。

LocalizedResources

LocalizedResources 元素包含以下属性：

属性	必须	描述
ID	是	用于唯一标识本地化资源的标识符。

LocalizedResources 元素包含以下元素：

元素	出现次数	说明
LocalizedCollections	0:n	在各种区域性中定义整个集合。一个集合可以包含不同的项数，以及适用于各种区域性的不同字符串。集合的示例包括声明类型中显示的枚举。例如，在下拉列表中向用户显示国家/地区列表。
LocalizedStrings	0:n	在各种区域性中定义所有字符串，但集合中出现的字符串除外。

LocalizedCollections

LocalizedCollections 元素包含以下元素：

元素	出现次数	说明
LocalizedCollection	1:n	支持的语言列表。

LocalizedCollection

LocalizedCollection 元素包含以下属性：

属性	必须	说明
ElementType	是	引用策略文件中的 ClaimType 元素或用户界面元素。
ElementId	是	一个字符串，包含当 ElementType 设置为 ClaimType 时使用的 ClaimsSchema 节中已定义的声明类型的引用。
TargetCollection	是	目标集合。

LocalizedCollection 元素包含以下元素：

元素	出现次数	说明
项目	0:n	定义可让用户在用户界面中为声明选择的可用选项，例如下拉列表中的值。

Item 元素包含以下属性：

属性	必须	说明
文本	是	应在用户界面中向用户显示的此选项的用户友好字符串。
Value	是	与此选项关联的字符串声明值。
SelectByDefault	否	指示默认情况下是否应在 UI 中选择此选项。可能的值：True 或 False。

以下示例演示了 LocalizedCollections 元素的用法。其中包含两个 LocalizedCollection 元素，一个元素适用于英语区域设置，另一个元素适用于西班牙语区域设置。这两个元素都设置了声明 Gender 的 Restriction 集合，以及适用于英语和西班牙语的项列表。有关更多示例，请查看声明限制枚举实时演示。

<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 元素包含以下属性：

属性	必须	说明
ElementType	是	可能的值：ClaimsProvider、ClaimType、ErrorMessage、GetLocalizedStringsTransformationClaimType、FormatLocalizedStringTransformationClaimType、Predicate、PredicateValidation 或 UxElement。
ElementId	是	如果 ElementType 设置为 `ClaimType`、`Predicate` 或 `PredicateValidation`，此元素包含对 ClaimsSchema 节中已定义的声明类型的引用。
StringId	是	如果 ElementType 设置为 `ClaimType`，此元素包含对声明类型的属性的引用。可能的值：`DisplayName`、`AdminHelpText` 或 `PatternHelpText`。 `DisplayName` 值用于设置声明显示名称。 `AdminHelpText` 值用于设置声明用户的帮助文本名称。 `PatternHelpText` 值用于设置声明模式帮助文本。如果 ElementType 设置为 `UxElement`，此元素包含对用户界面元素的属性的引用。如果 ElementType 设置为 `ErrorMessage`，此元素指定错误消息的标识符。有关 `UxElement` 标识符的完整列表，请参阅本地化字符串 ID。

ElementType

ElementType 引用策略中要本地化的声明类型、声明转换或用户界面元素。

要本地化的元素	ElementType	ElementId	StringId
标识提供者名称	`ClaimsProvider`		ClaimsExchange 元素的 ID
声明类型特性	`ClaimType`	声明类型的名称	要本地化的声明的特性。可能的值：`AdminHelpText`、`DisplayName`、`PatternHelpText` 和 `UserHelpText`。
错误消息	`ErrorMessage`		错误消息的 ID
将已本地化的字符串复制到声明中	`GetLocalizedStringsTra nsformationClaimType`		输出声明的名称
谓词用户消息	`Predicate`	谓词的名称	要本地化的谓词的特性。可能的值：`HelpText`。
谓词组用户消息	`PredicateValidation`	PredicateValidation 元素的 ID。	PredicateGroup 元素的 ID。谓词组必须是 ElementId 中定义的谓词验证元素的子级。
用户界面元素	`UxElement`		要本地化的用户界面元素的 ID。
显示控件	`DisplayControl`	显示控件的 ID。	要本地化的用户界面元素的 ID。

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

后续步骤

有关本地化示例，请参阅以下文章：

本地化元素

SupportedLanguages

SupportedLanguages

LocalizedResources

LocalizedCollections

LocalizedCollection

LocalizedStrings

ElementType

ClaimType

ErrorMessage

FormatLocalizedStringTransformationClaimType

GetLocalizedStringsTransformationClaimType

Predicate

PredicateValidation

UxElement

DisplayControl

后续步骤

其他资源