重要
自 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>
...
后续步骤
有关本地化示例,请参阅以下文章: