Localize login and end-user pages
Identity Cloud lets you localize login and end-user pages to support the different languages of your
end users. Use ISO-639-1 language codes (for
example fr
and de
) to provide locale specific content in as many locales as you need.
Localize at feature level
Localize related features
You can localize the following features related to journey and account pages:
Feature | Description |
---|---|
Hosted pages |
Refer to Localize headers and footers and Localize the favicon and theme logo. |
Security questions |
Refer to Security questions. |
Terms and conditions |
Refer to Terms and conditions. |
Email templates |
Refer to Email templates. |
Localize journey authentication nodes
You can individually localize authentication nodes that display content in journey pages. For example, the Page node lets you add content to the Page Header property to display an initial journey message to end users. You can define as many localized versions of the message as you need:
Localize at UI level
You can localize static content and server messages in the login and end-user UIs using translation configuration. Translation configuration lets you define a locale-specific set of key/phrase translation pairs that override the default set of key/phrase pairs. You can override some or all of the default keys, in as many locales as you need. The translation configuration has an effect in all realms.
The UIs try to find a translation configuration for the locale requested by an end user’s browser.
If no locale is found, Identity Cloud defaults to using the en
(English) locale.
To manage translation configuration, use the /openidm/config/uilocale/*
endpoint in the REST API.
Translation configuration format
The translation configuration format for each locale includes the following:
{
"enduser": {(1)
"pages": {
"dashboard": {
"widgets": {
"welcome": {
"greeting": "Translation for predefined 'greeting' key",(2)
}
}
}
},
"overrides": {
"FirstName": "Translation for literal phrase 'First Name'",(3)
"LastName": "Translation for literal phrase 'Last Name'"(3)
}
},
"login": {(1)
"login": {
"next": "Translation for predefined 'next' key"(2)
},
"overrides": {
"UserName": "Translation for literal phrase 'User Name'",(3)
"Password": "Translation for literal phrase 'Password'"(3)
}
},
"shared": {(1)
"sideMenu": {
"dashboard": "Translation for predefined 'dashboard' key"(2)
}
}
}
1 | Top-level blocks The |
||
2 | Key/phrase translation pairs with predefined keys
Key/phrase translation pairs are predefined in the
|
||
3 | Key/phrase translation pairs with literal keys Key/phrase translation pairs defined within an Define translation pairs with literal keys to be a catch-all solution for any UI phrases that have not been defined, or for any unlocalized phrases that come directly from the backend servers. The example under the
|
Translation precedence and fall back
The UIs translate each key/phrase pair in a particular order. They initially determine a primary
locale using the requested language from an end user’s browser. If no translation is found using
the primary locale, they fall back to the default en
locale.
The translation precedence for an end user with a browser locale of fr
(French) is:
-
Attempt to use the primary
fr
locale:Look for the translation key in any translation configuration for the
fr
locale:https://<tenant-env-fqdn>/openidm/config/uilocale/fr
If the translation configuration is not present, a
404
response is returned.
-
Fall back to the default
en
locale:-
Look for the translation key in any translation configuration for the
en
locale:
https://<tenant-env-fqdn>/openidm/config/uilocale/en
If the translation configuration is not present, a
404
response is returned. -
Look for the translation key in the translation files for the
en
locale :-
platform-enduser/src/locales/en.json
-
platform-login/src/locales/en.json
-
platform-shared/src/locales/en.json
-
-
You may notice one or more 404
responses in the browser console for the /openidm/config/uilocale/*
endpoint. These are expected and do not indicate a UI error; the 404
responses mean that the UI
cannot locate a translation configuration override, which is valid if you have not added
one.
To suppress the 404
responses,
create a translation configuration with an
empty body for each locale reporting a 404
response.
REST API
Create or replace translation configuration
-
Create an access token for the realm where you want to apply the translation.
-
Create or replace the translation configuration for each locale:
Show request
$ curl \ --request PUT 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) --header 'Authorization: Bearer <access-token>' \(2) --header 'Content-Type: application/json' \ --data-raw '{(3) "enduser": { "pages": { "dashboard": { "widgets": { "welcome": { "greeting": "Bonjour" } } } }, "overrides": { "FirstName": "Prénom", "LastName": "Nom de famille" } }, "login": { "login": { "next": "Suivant" }, "overrides": { "UserName": "Nom d'\''utilisateur", "Password": "Mot de passe" } }, "shared": { "sideMenu": { "dashboard": "Tableau de bord" } } } '
1 Replace <locale> with a locale identifier. Some examples are: -
en
(English) -
es
(Spanish) -
fr
(French) -
en-us
(English - United States) -
es-ar
(Spanish - Argentina) -
fr-ca
(French - Canada)
2 Replace <access-token> with the access token. 3 Replace the example translation configuration with your own translation configuration. Show response
{ "_id": "uilocale/fr", "enduser": { "pages": { "dashboard": { "widgets": { "welcome": { "greeting": "Bonjour" } } } }, "overrides": { "FirstName": "Prénom", "LastName": "Nom de famille" } }, "login": { "login": { "next": "Suivant" }, "overrides": { "UserName": "Nom d'utilisateur", "Password": "Mot de passe" } }, "shared": { "sideMenu": { "dashboard": "Tableau de bord" } } }
the locale you specify in the PUT request becomes the name of the corresponding backend JSON file. For example, if the locale you create is fr
, then the backend JSON file would befr.json
. -
View translation configuration
You do not need an access token to view the translation configuration because it is publicly accessible.
-
View the translation configuration using a GET request:
Show request
$ curl \ --request GET 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) --header 'Authorization: Bearer <access-token>' (2)
1 Replace <locale> with a locale identifier, such as fr
.2 Replace <access-token> with the access token. Show response
{ "_id": "uilocale/fr", "enduser": { "pages": { "dashboard": { "widgets": { "welcome": { "greeting": "Bonjour" } } } }, "overrides": { "FirstName": "Prénom", "LastName": "Nom de famille" } }, "login": { "login": { "next": "Suivant" }, "overrides": { "UserName": "Nom d'utilisateur", "Password": "Mot de passe" } }, "shared": { "sideMenu": { "dashboard": "Tableau de bord" } } }
When attempting to view the default
en
translation, as described in View translation configuration, no results are returned. To view the defaulten
translation, refer to the following UI package files:If you receive a
404
response, the locale is not defined. To create a locale, refer to Create or replace translation configuration.
Delete translation configuration
-
Create an access token for the realm where the translations are applied.
-
Delete the translation configuration:
Show request
$ curl \ --request DELETE 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) --header 'Authorization: Bearer <access-token>' (2)
1 Replace <locale> with a locale identifier, such as fr
.2 Replace <access-token> with the access token. Show response
{ "_id": "uilocale/fr", "enduser": { "pages": { "dashboard": { "widgets": { "welcome": { "greeting": "Bonjour" } } } }, "overrides": { "FirstName": "Prénom", "LastName": "Nom de famille" } }, "login": { "login": { "next": "Suivant" }, "overrides": { "UserName": "Nom d'utilisateur", "Password": "Mot de passe" } }, "shared": { "sideMenu": { "dashboard": "Tableau de bord" } } }