Localize Identity Cloud end-user and login UIs
Overview
You can localize the Identity Cloud end-user and login UIs to support the different languages of your end users. You do this with translation configuration, defining 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, or gracefully fall back to the default en
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 is as follows:
{
"enduser": {(1)
"pages": {
"dashboard": {
"widgets": {
"welcome": {
"greeting": "Translation for predefined 'greeting' key",(2)
}
}
}
}
},
"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 Most of the key/phrase translation pairs are predefined in the You can translate some or all of the keys. Additionally, if you want to create different translations in the |
||
3 | Key/phrase translation pairs with literal keys Key/phrase translation pairs defined within an
|
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. Then, 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) would be as follows:
-
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/frIf the translation configuration is not present, a 404 response is returned. See Translation 404 responses.
-
-
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/enIf the translation configuration is not present, a 404 response is returned. See Translation 404 responses.
-
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
-
-
Translation 404 responses
You may see 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 perfectly valid if you have not added
one.
If you would prefer 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. See Get an access token.
-
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" } } } } }, "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" } } } } }, "login": { "login": { "next": "Suivant" }, "overrides": { "UserName": "Nom d'\''utilisateur", "Password": "Mot de passe" } }, "shared": { "sideMenu": { "dashboard": "Tableau de bord" } } }
-
View translation configuration
An access token is not needed to to view the translation configuration as 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)
1 Replace <locale> with a locale identifier. Show response
{ "_id": "uilocale/fr", "enduser": { "pages": { "dashboard": { "widgets": { "welcome": { "greeting": "Bonjour" } } } } }, "login": { "login": { "next": "Suivant" }, "overrides": { "UserName": "Nom d'\''utilisateur", "Password": "Mot de passe" } }, "shared": { "sideMenu": { "dashboard": "Tableau de bord" } } }
Delete translation configuration
-
Create an access token for the realm where the translations are applied. See Get an access token.
-
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. 2 Replace <access-token> with the access token. Show response
{ "_id": "uilocale/fr", "enduser": { "pages": { "dashboard": { "widgets": { "welcome": { "greeting": "Bonjour" } } } } }, "login": { "login": { "next": "Suivant" }, "overrides": { "UserName": "Nom d'\''utilisateur", "Password": "Mot de passe" } }, "shared": { "sideMenu": { "dashboard": "Tableau de bord" } } }