Skip to content

Commit 54880dd

Browse files
v-albemiv-albemi
authored
Merge pull request #110311 from yoelhor/patch-29
Update localization.md
2 parents 696c575 + cf69e46 commit 54880dd

File tree

1 file changed

+165
-40
lines changed

1 file changed

+165
-40
lines changed

‎articles/active-directory-b2c/localization.md

Lines changed: 165 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ manager: celestedg
88
ms.service: active-directory
99
ms.workload: identity
1010
ms.topic: reference
11-
ms.date: 03/11/2020
11+
ms.date: 04/20/2020
1212
ms.author: mimart
1313
ms.subservice: B2C
1414
---
@@ -142,65 +142,190 @@ The **LocalizedString** element contains the following attributes:
142142

143143
| Attribute | Required | Description |
144144
| --------- | -------- | ----------- |
145-
| ElementType | Yes | A reference to a claim type element or a user interface element in the policy. Possible values: `ClaimType`, `UxElement`, `ErrorMessage`, `Predicate`, or `GetLocalizedStringsTransformationClaimType`. The `ClaimType` value is used to localize one of the claim attributes, as specified in the StringId. The `UxElement` value is used to localize one of the user interface elements as specified in the StringId. The `ErrorMessage` value is used to localize one of the system error messages as specified in the StringId. The `Predicate` value is used to localize one of the [Predicate](predicates.md) error messages, as specified in the StringId. The `InputValidation` value is used to localize one of the [PredicateValidation](predicates.md) group error messages as specified in the StringId. The `GetLocalizedStringsTransformationClaimType` value is used to copy localized strings into claims. For more information, see [GetLocalizedStringsTransformation claims transformation](string-transformations.md#getlocalizedstringstransformation) |
145+
| ElementType | Yes | Possible values: [ClaimsProvider](#claimsprovider), [ClaimType](#claimtype), [ErrorMessage](#errormessage), [GetLocalizedStringsTransformationClaimType](#getlocalizedstringstransformationclaimtype), [Predicate](#predicate), [InputValidation](#inputvalidation), or [UxElement](#uxelement). |
146146
| ElementId | Yes | If **ElementType** is set to `ClaimType`, `Predicate`, or `InputValidation`, this element contains a reference to a claim type already defined in the ClaimsSchema section. |
147147
| StringId | Yes | If **ElementType** is set to `ClaimType`, this element contains a reference to an attribute of a claim type. Possible values: `DisplayName`, `AdminHelpText`, or `PatternHelpText`. The `DisplayName` value is used to set the claim display name. The `AdminHelpText` value is used to set the help text name of the claim user. The `PatternHelpText` value is used to set the claim pattern help text. If **ElementType** is set to `UxElement`, this element contains a reference to an attribute of a user interface element. If **ElementType** is set to `ErrorMessage`, this element specifies the identifier of an error message. See [Localization string IDs](localization-string-ids.md) for a complete list of the `UxElement` identifiers.|
148148

149+
## ElementType
149150

150-
The following example shows a localized sign-up page. The first three **LocalizedString** values set the claim attribute. The third changes the value of the continue button. The last one changes the error message.
151+
The ElementType reference to a claim type, a claim transformation, or a user interface element in the policy to be localized.
151152

152-
```XML
153-
<LocalizedResources Id="api.selfasserted.en">
154-
<LocalizedStrings>
155-
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="DisplayName">Email</LocalizedString>
156-
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="UserHelpText">Please enter your email</LocalizedString>
157-
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="PatternHelpText">Please enter a valid email address</LocalizedString>
158-
<LocalizedString ElementType="UxElement" StringId="button_continue">Create new account</LocalizedString>
159-
<LocalizedString ElementType="ErrorMessage" StringId="UserMessageIfClaimsPrincipalAlreadyExists">The account you are trying to create already exists, please sign-in.</LocalizedString>
160-
</LocalizedStrings>
161-
</LocalizedResources>
153+
| Element to localize | ElementType | ElementId |StringId |
154+
| --------- | -------- | ----------- |----------- |
155+
| Identity provider name |`ClaimsProvider`| | The ID of the ClaimsExchange element|
156+
| Claim type attributes|`ClaimType`|Name of the claim type| The attribute of the claim to be localized. Possible values: `AdminHelpText`, `DisplayName`, `PatternHelpText`, and `UserHelpText`.|
157+
|Error message|`ErrorMessage`||The ID of the error message |
158+
|Copies localized strings into claims|`GetLocalizedStringsTra nsformationClaimType`||The name of the output claim|
159+
|Predicate user message|`Predicate`|The name of the predicate| The attribute of the predicate to be localized. Possible values: `HelpText`.|
160+
|Predicate group user message|`InputValidation`|The ID of the PredicateValidation element.|The ID of the PredicateGroup element. The predicate group must be a child of the predicate validation element as defined in the ElementId.|
161+
|User interface elements |`UxElement` | | The ID of the user interface element to be localized.|
162+
163+
## Examples
164+
165+
### ClaimsProvider
166+
167+
The ClaimsProvider value is used to localize one of the claim providers display name.
168+
169+
```xml
170+
<OrchestrationStep Order="2" Type="ClaimsExchange">
171+
...
172+
<ClaimsExchanges>
173+
<ClaimsExchange Id="FacebookExchange" TechnicalProfileReferenceId="Facebook-OAUTH" />
174+
<ClaimsExchange Id="GoogleExchange" TechnicalProfileReferenceId="Google-OAUTH" />
175+
<ClaimsExchange Id="LinkedInExchange" TechnicalProfileReferenceId="LinkedIn-OAUTH" />
176+
</ClaimsExchanges>
177+
</OrchestrationStep>
178+
179+
```
180+
181+
The following example shows how to localize claim providers' display name.
182+
183+
```xml
184+
<LocalizedString ElementType="ClaimsProvider" StringId="FacebookExchange">Facebook</LocalizedString>
185+
<LocalizedString ElementType="ClaimsProvider" StringId="GoogleExchange">Google</LocalizedString>
186+
<LocalizedString ElementType="ClaimsProvider" StringId="LinkedInExchange">LinkedIn</LocalizedString>
162187
```
163188

164-
The following example shows a localized the **UserHelpText** of **Predicate** with Id `IsLengthBetween8And64`. And a localized **UserHelpText** of **PredicateGroup** with Id `CharacterClasses` of **PredicateValidation** with Id `StrongPassword`.
189+
### ClaimType
190+
191+
The ClaimType value is used to localize one of the claim attributes.
192+
193+
```xml
194+
<ClaimType Id="email">
195+
<DisplayName>Email Address</DisplayName>
196+
<DataType>string</DataType>
197+
<UserHelpText>Email address that can be used to contact you.</UserHelpText>
198+
<UserInputType>TextBox</UserInputType>
199+
</ClaimType>
200+
```
201+
202+
The following example shows how to localize the DisplayName, UserHelpText, and PatternHelpText attributes of the email claim type.
165203

166204
```XML
167-
<PredicateValidation Id="StrongPassword">
168-
<PredicateGroups>
169-
...
170-
<PredicateGroup Id="CharacterClasses">
171-
...
172-
</PredicateGroup>
173-
</PredicateGroups>
174-
</PredicateValidation>
175-
176-
...
177-
178-
<Predicate Id="IsLengthBetween8And64" Method="IsLengthRange">
205+
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="DisplayName">Email</LocalizedString>
206+
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="UserHelpText">Please enter your email</LocalizedString>
207+
<LocalizedString ElementType="ClaimType" ElementId="email" StringId="PatternHelpText">Please enter a valid email address</LocalizedString>
208+
```
209+
210+
### ErrorMessage
211+
212+
The ErrorMessage value is used to localize one of the system error messages.
213+
214+
```xml
215+
<TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
216+
<Metadata>
217+
<Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">true</Item>
218+
<Item Key="UserMessageIfClaimsPrincipalAlreadyExists">You are already registered, please press the back button and sign in instead.</Item>
219+
</Metadata>
179220
...
180-
</Predicate>
181-
...
221+
</TechnicalProfile>
222+
```
182223

224+
The following example shows how to localize the UserMessageIfClaimsPrincipalAlreadyExists error message.
183225

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

186-
<LocalizedString ElementType="Predicate" ElementId="IsLengthBetween8And64" StringId="HelpText">The password must be between 8 and 64 characters.</LocalizedString>
227+
```XML
228+
<LocalizedString ElementType="ErrorMessage" StringId="UserMessageIfClaimsPrincipalAlreadyExists">The account you are trying to create already exists, please sign-in.</LocalizedString>
187229
```
188230

189-
## Set up localization
231+
### GetLocalizedStringsTransformationClaimType
190232

191-
This article shows you how to support multiple locales or languages in the policy for user journeys. Localization requires three steps: set-up the explicit list of the supported languages, provide language-specific strings and collections, and edit the ContentDefinition for the page.
233+
The GetLocalizedStringsTransformationClaimType value is used to copy localized strings into claims. For more information, see [GetLocalizedStringsTransformation claims transformation](string-transformations.md#getlocalizedstringstransformation)
192234

193-
### Set up the explicit list of supported languages
194235

195-
Under the **BuildingBlocks** element, add the **Localization** element with the list of supported languages. The following example shows how to define the localization support for both English (default) and Spanish:
236+
```xml
237+
<ClaimsTransformation Id="GetLocalizedStringsForEmail" TransformationMethod="GetLocalizedStringsTransformation">
238+
<OutputClaims>
239+
<OutputClaim ClaimTypeReferenceId="subject" TransformationClaimType="email_subject" />
240+
<OutputClaim ClaimTypeReferenceId="message" TransformationClaimType="email_message" />
241+
<OutputClaim ClaimTypeReferenceId="codeIntro" TransformationClaimType="email_code" />
242+
<OutputClaim ClaimTypeReferenceId="signature" TransformationClaimType="email_signature" />
243+
</OutputClaims>
244+
</ClaimsTransformation>
245+
```
246+
247+
The following example shows how to localize output claims of the GetLocalizedStringsTransformation claims transformation.
248+
249+
```xml
250+
<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_subject">Contoso account email verification code</LocalizedString>
251+
<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_message">Thanks for verifying your account!</LocalizedString>
252+
<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_code">Your code is</LocalizedString>
253+
<LocalizedString ElementType="GetLocalizedStringsTransformationClaimType" StringId="email_signature">Sincerely</LocalizedString>
254+
```
255+
256+
### Predicate
257+
258+
The Predicate value is used to localize one of the [Predicate](predicates.md) error messages.
259+
260+
```xml
261+
<Predicates>
262+
<Predicate Id="LengthRange" Method="IsLengthRange" HelpText="The password must be between 6 and 64 characters.">
263+
<Parameters>
264+
<Parameter Id="Minimum">6</Parameter>
265+
<Parameter Id="Maximum">64</Parameter>
266+
</Parameters>
267+
</Predicate>
268+
<Predicate Id="Lowercase" Method="IncludesCharacters" HelpText="a lowercase letter">
269+
<Parameters>
270+
<Parameter Id="CharacterSet">a-z</Parameter>
271+
</Parameters>
272+
</Predicate>
273+
<Predicate Id="Uppercase" Method="IncludesCharacters" HelpText="an uppercase letter">
274+
<Parameters>
275+
<Parameter Id="CharacterSet">A-Z</Parameter>
276+
</Parameters>
277+
</Predicate>
278+
</Predicates>
279+
```
280+
281+
The following example shows how to localize predicates help text.
282+
283+
```xml
284+
<LocalizedString ElementType="Predicate" ElementId="LengthRange" StringId="HelpText">The password must be between 6 and 64 characters.</LocalizedString>
285+
<LocalizedString ElementType="Predicate" ElementId="Lowercase" StringId="HelpText">a lowercase letter</LocalizedString>
286+
<LocalizedString ElementType="Predicate" ElementId="Uppercase" StringId="HelpText">an uppercase letter</LocalizedString>
287+
```
288+
289+
### InputValidation
290+
291+
The InputValidation value is used to localize one of the [PredicateValidation](predicates.md) group error messages.
292+
293+
```xml
294+
<PredicateValidations>
295+
<PredicateValidation Id="CustomPassword">
296+
<PredicateGroups>
297+
<PredicateGroup Id="LengthGroup">
298+
<PredicateReferences MatchAtLeast="1">
299+
<PredicateReference Id="LengthRange" />
300+
</PredicateReferences>
301+
</PredicateGroup>
302+
<PredicateGroup Id="CharacterClasses">
303+
<UserHelpText>The password must have at least 3 of the following:</UserHelpText>
304+
<PredicateReferences MatchAtLeast="3">
305+
<PredicateReference Id="Lowercase" />
306+
<PredicateReference Id="Uppercase" />
307+
<PredicateReference Id="Number" />
308+
<PredicateReference Id="Symbol" />
309+
</PredicateReferences>
310+
</PredicateGroup>
311+
</PredicateGroups>
312+
</PredicateValidation>
313+
</PredicateValidations>
314+
```
315+
316+
The following example shows how to localize a predicate validation group help text.
196317

197318
```XML
198-
<Localization Enabled="true">
199-
<SupportedLanguages DefaultLanguage="en" MergeBehavior="ReplaceAll">
200-
<SupportedLanguage>en</SupportedLanguage>
201-
<SupportedLanguage>es</SupportedLanguage>
202-
</SupportedLanguages>
203-
</Localization>
319+
<LocalizedString ElementType="InputValidation" ElementId="CustomPassword" StringId="CharacterClasses">The password must have at least 3 of the following:</LocalizedString>
320+
```
321+
322+
### UxElement
323+
324+
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.
325+
326+
```XML
327+
<LocalizedString ElementType="UxElement" StringId="button_continue">Create new account</LocalizedString>
328+
<LocalizedString ElementType="UxElement" StringId="button_cancel">Cancel</LocalizedString>
204329
```
205330

206331
## Next steps

0 commit comments

Comments
 (0)