Localization 元素

项目
2025-05-18

重要

自 2025 年 5 月 1 日起，Azure AD B2C 将不再可供新客户购买。在我们的常见问题解答中了解详细信息。

注释

在 Azure Active Directory B2C 中，自定义策略主要用于解决复杂场景。对于大多数场景，我们建议您使用内置的用户流。如果未这样做，请通过 Active Directory B2C 中的自定义策略入门来了解自定义策略初学者包。

本地化元素允许你在用户旅程的策略中支持多个区域设置或语言。通过策略中的本地化支持，可以：

在策略中设置受支持语言的显式列表，并选取默认语言。
提供特定于语言的字符串和集合。

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

特征	必选	DESCRIPTION
已启用	否	可能的值：`true` 或 `false`。

本地化元素包含以下 XML 元素

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

SupportedLanguages

SupportedLanguages 元素包含以下属性：

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

SupportedLanguages

SupportedLanguages 元素包含以下元素：

元素	出现次数	DESCRIPTION
SupportedLanguage	1：n	显示符合每个 RFC 5646 - 标识语言标记的语言标记的内容。

LocalizedResources

LocalizedResources 元素包含以下属性：

特征	必选	DESCRIPTION
ID	是的	用于唯一标识本地化资源的标识符。

LocalizedResources 元素包含以下元素：

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

LocalizedCollections

LocalizedCollections 元素包含以下元素：

元素	出现次数	DESCRIPTION
LocalizedCollection	1：n	支持的语言列表。

LocalizedCollection

LocalizedCollection 元素包含以下属性：

特征	必选	DESCRIPTION
ElementType	是的	引用策略文件中的 ClaimType 元素或用户界面元素。
ElementId	是的	一个字符串，其中包含对 ClaimsSchema 节中已定义的声明类型的引用，如果 ElementType 设置为 ClaimType ，则使用该类型。
TargetCollection	是的	目标集合。

LocalizedCollection 元素包含以下元素：

元素	出现次数	DESCRIPTION
条目	0：n	定义一个可供用户在用户界面中选择声明的可用选项，例如下拉列表中的值。

Item 元素包含以下属性：

特征	必选	DESCRIPTION
文本	是的	用户友好的显示字符串，应在用户界面中为此选项显示给用户。
价值	是的	与选择此选项关联的字符串声明值。
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 元素包含以下元素：

元素	出现次数	DESCRIPTION
LocalizedString	1：n	本地化字符串。

LocalizedString 元素包含以下属性：

特征	必选	DESCRIPTION
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`。

ElementType

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

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

索赔类型

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>

FormatLocalizedStringTransformationClaimType

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>

谓词

谓词值用于本地化谓词错误消息之一。

<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 值用于本地化谓词Validation 组错误消息之一。

<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

索赔类型

错误消息

FormatLocalizedStringTransformationClaimType

GetLocalizedStringsTransformationClaimType

谓词

PredicateValidation

UxElement

DisplayControl

后续步骤

其他资源