--- title: Supplementary information for tenant localization description: "Reference for Advanced Identity Cloud localization: language set format, enum label translations, locale fallback logic, and suppressing 404 errors." component: pingoneaic page_id: pingoneaic:tenants:tenant-localize-supplementary-information canonical_url: https://docs.pingidentity.com/pingoneaic/tenants/tenant-localize-supplementary-information.html llms_txt: https://docs.pingidentity.com/pingoneaic/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md section_ids: language-set-format: Language set format translating-enum-values: Localize enum display labels set-enum-display-labels-using-the-api: Set enum display labels using the API set-enum-display-labels-using-the-admin-console: Set enum display labels using the admin console translation-logic: Translation logic example-of-translation-logic-with-a-four-letter-locale: Example of translation logic with a four-letter locale example-of-translation-logic-with-a-two-letter-locale: Example of translation logic with a two-letter locale suppress-404-responses: Suppress 404 responses --- # Supplementary information for tenant localization This page provides supplementary information on localization in PingOne Advanced Identity Cloud, including the language set format, enum label translations, locale fallback logic, and suppressing 404 errors. ## Language set format A language set has the following JSON structure: ```json { "_meta": { (4) "lastUpdated": "2026-07-23T12:44:36.345Z", "status": true, "updatedBy": "admin.user@pingidentity.com", "updatedByFullName": "Admin User" }, "admin": { (1) "sideMenu": { "securityQuestions": "Translation for predefined 'securityQuestions' key" (2) }, "overrides": { "EmailAddress": "Translation for literal phrase 'Email Address'", (3) "Name": "Translation for literal word 'Name'", (3) "Owners": "Translation for literal word 'Owners'", (3) "AppLogoURI": "Translation for literal phrase 'App Logo URI'" (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) "UnabletoresumesessionItmayhaveexpired": "Translation for literal phrase 'Unable to resume session. It may have expired.'" (3) } }, "shared": { (1) "sideMenu": { "dashboard": "Translation for predefined 'dashboard' key" (2) } }, "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) } } } ``` | | | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **1** | The [`admin`](https://github.com/ForgeRock/platform-ui/tree/master/packages/platform-admin), [`login`](https://github.com/ForgeRock/platform-ui/tree/master/packages/platform-login), [`shared`](https://github.com/ForgeRock/platform-ui/tree/master/packages/platform-shared), and [`enduser`](https://github.com/ForgeRock/platform-ui/tree/master/packages/platform-enduser) top-level blocks correspond to the names of their respective UI packages in GitHub. | | **2** | Key-value translation pairs with *predefined* keys.Key-value translation pairs represent all text output that Advanced Identity Cloud presents by default. They're predefined in the `en` locale translation files for each package:- - - - Use the packages to find the built-in key-value translations so that you can define translations for your locale. To create different translations in the admin, enduser, and login blocks for a key from the shared block, copy the JSON structure for the shared key into each of the admin, enduser, and login blocks. This overrides the key in the shared block. | | **3** | Key-value translation pairs with *literal* keys.Key-value translation pairs defined within an `overrides` block aren't predefined. Instead, the key is made from a literal phrase with all non-alphanumeric characters (including underscores) stripped out.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 `login` top-level block shows two literal keys that translate the placeholder text from input fields that are part of an authentication journey. This approach can be taken to translate server output from authentication messages and journey nodes. The example under the `enduser` top-level block shows a similar approach that translates output from the hosted account pages. You can also add an overrides block to the shared top-level block. This is particularly useful for providing user-friendly display names for enum values defined in managed object schemas. Learn more in enum labels and localization. | | **4** | The `_meta` block is automatically generated and updated by the Advanced Identity Cloud admin console when a language set is created or modified. It contains metadata about the language set, including the last update timestamp, status (active or inactive), and the tenant administrator who made the last update. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Advanced Identity Cloud supports UTF-8 character encoding across the admin console, hosted account pages, and hosted journey pages, allowing you to present translated text in many languages. However, the user interface does not currently support right-to-left (RTL) layout rendering. Providing Arabic or Hebrew translations using language sets will localize the text strings, but it doesn't adjust the visual layout to be RTL-aware. | ## Localize `enum` display labels Managed objects can be defined with an `enum` (enumeration) property, which restricts possible values to a defined set of options. For example, a `flight` field could have `enum: ["flying", "landing", "lost"]`, a `shirtSize` field could have `enum: ["S", "M", "L", "XL"]`, or a `favoriteColor` field could have `"enum": ["red","green","blue"]`. You can use the raw values from these `enum` lists (`lost`, `blue`, `XL`) as keys within an `overrides` block in the translation configuration. This allows you to provide more user-friendly display labels or localized translations when presented in the UI. ### Set `enum` display labels using the API Typically, these overrides are placed in the `shared.overrides` block if the labels need to be consistently translated. However, they can also be placed in a context-specific `shared.pingTranslations.enum` block if a particular managed object requires different labels for the same `enum` values. Example setting German translations: ```bash curl \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "_id": "uilocale/de", "shared": { "overrides": {(1) "red": "Rot", "green": "Grün", "blue": "Blau" }, "pingTranslations": { "enum": { "favoriteColor": {(2) "red": "Dunkel Rot", "green": "Wald Grün", "blue": "Meer Blau" } } } } }' \ "https:///openidm/config/uilocale/de" { "_id": "uilocale/de", "_rev": "...", "shared": { "overrides": { "red": "Rot", "green": "Grün", "blue": "Blau" }, "pingTranslations": { "enum": { "favoriteColor": { "red": "Dunkel Rot", "green": "Wald Grün", "blue": "Meer Blau" } } } } } ``` | | | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **1** | Use the `shared.overrides` block to provide translations for `enum` values that are consistent across all managed objects. | | **2** | Use the `shared.pingTranslations.enum` block to provide translations for `enum` values that are specific to a particular managed object. In this example, the `favoriteColor` managed object has its own translations for the `enum` values. | ### Set `enum` display labels using the admin console To set `enum` display labels using the admin console, create custom translations using the instructions in step 6 in [Edit a language set](tenant-localize-ui.html#edit-a-language-set). This sets the translations in the `shared.overrides` block. ## Translation logic The Advanced Identity Cloud admin console, hosted journey pages, and hosted account pages use logic that translates each key-value pair in a particular order. The translation logic initially determines a primary locale using the requested language from a tenant administrator's browser (admin console) or end user's browser (hosted journey pages and hosted account pages). If the locale is a two-letter language locale (for example, `es`) and no translation is found using that locale, the logic falls back to the default `en` locale. If the locale is a four-letter language and region locale (for example, `es-ar`) and no translation is found using that locale, the logic first falls back to the parent two-letter language locale (for example, `es`) and if no translation is found using that locale, the logic falls back to the default `en` locale. ### Example of translation logic with a four-letter locale An example of the translation logic for a browser with a four-letter locale of `fr-ca` (French Canadian) is: 1. Attempt to use the primary `fr-ca` locale: Look for the translation key in the language set for the `fr-ca` locale:\ `https:///openidm/config/uilocale/fr-ca` * If the language set is present: * Look in one of the `admin`, `enduser`, or `login` top-level blocks, depending on the context of the request. * Look in the `shared` top-level block. * If the language set isn't present, a `404` response is returned. 2. Fall back to the `fr` locale: Look for the translation key in the language set for the `fr` locale:\ `https:///openidm/config/uilocale/fr` * If the language set is present: * Look in one of the `admin`, `enduser`, or `login` top-level blocks, depending on the context of the request. * Look in the `shared` top-level block. * If the language set isn't present, a `404` response is returned. 3. Fall back to the default locale (if the default locale isn't `en`): Look for the translation key in the language set for the default locale. * If the language set is present: * Look in one of the `admin`, `enduser`, or `login` top-level blocks, depending on the context of the request. * Look in the `shared` top-level block. 4. Fall back to the `en` locale: 1. Look for the translation key in the language set for the `en` locale:\ `https:///openidm/config/uilocale/en` * Look in one of the `admin`, `enduser`, or `login` top-level blocks, depending on the context of the request. * Look in the `shared` top-level block. * If the language set isn't present, a `404` response is returned. 2. Look for the translation key in the built-in translation files for the `en` locale: * Look in one of the `admin`, `enduser`, or `login` built-in translation files, depending on the context of the request. * `platform-admin/src/locales/en.json` * `platform-enduser/src/locales/en.json` * `platform-login/src/locales/en.json` * Look in the `shared` built-in translation file: * `platform-shared/src/locales/en.json` ### Example of translation logic with a two-letter locale The translation logic for a browser with a two-letter locale of `fr` (French) follows the same logic as in [Example of translation logic with a four-letter locale](#example-of-translation-logic-with-a-four-letter-locale), starting at step 2. ## Suppress 404 responses 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 [translation logic](#translation-logic) can't locate a language set override, which is valid if you've not added one. To suppress this behavior, do the following for each locale reporting a `404` response: * Use the admin console to [add a language set](tenant-localize-ui.html#add-a-language-set) with no translations in it. * Use the REST API to [create a language set](tenant-localize-api.html#create-or-replace-a-language-set) with an empty body. The translation logic will still work as expected with no loss of functionality, falling back through locales until it finds a translation for each key.