PingOne Advanced Identity Cloud

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:

{
  "_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, login, shared, and 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:
curl \
--header "Authorization: Bearer <access-token>" \
--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://<tenant-env-fqdn>/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. 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://<tenant-env-fqdn>/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://<tenant-env-fqdn>/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://<tenant-env-fqdn>/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, 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 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:

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.