PingOne Advanced Identity Cloud

Configure tenant localization

You can localize static content and server messages in the Advanced Identity Cloud admin, 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 Advanced Identity Cloud UIs try to find a translation configuration for the locale requested by the browser of a tenant administrator (admin UI) or an end user (login UI and end-user UI). If no locale is found, Advanced 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:

{
    "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)
        }
    },
    "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)
            "UnabletoresumesessionItmayhaveexpired": "Translation for literal phrase 'Unable to resume session. It may have expired.'"(3)
        }
    },
    "shared": {(1)
        "sideMenu": {
            "dashboard": "Translation for predefined 'dashboard' key"(2)
        }
    }
}
1 Top-level blocks

The admin, enduser, login, and shared top-level blocks correspond to the names of these UI packages in GitHub:
2 Key/phrase translation pairs with predefined keys

Key/phrase translation pairs represent all text output that Advanced Identity Cloud presents by default. They are predefined in the en locale translation files for each package:

Use the packages to find the default key/phrase 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/phrase translation pairs with literal keys

Key/phrase translation pairs defined within an override block are not 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 end-user account pages.

You can also add an override block to the shared top-level block.

Translation process

The Advanced Identity Cloud admin, login, and end-user UIs use a process that translates each key/phrase pair in a particular order.

The translation process initially determines a primary locale using the requested language from a tenant administrator’s browser (admin UI) or end user’s browser (login UI and end-user UI). If the locale is a two-letter language locale (for example, es) and no translation is found using that locale, the process 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 process first falls back to the parent two-letter language locale (for example, es) and if no translation is found using that locale, the process falls back to the default en locale.

Example of translation process with a four-letter locale

An example of the translation process 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 any translation configuration for the fr-ca locale:
    https://<tenant-env-fqdn>/openidm/config/uilocale/fr-ca

    If the translation configuration is not present, a 404 response is returned.

  2. Fall back to the 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.

  3. Fall back to the default en locale:

    1. 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.

    2. Look for the translation key in the translation files for the en locale :

      • platform-admin/src/locales/en.json

      • platform-enduser/src/locales/en.json

      • platform-login/src/locales/en.json

      • platform-shared/src/locales/en.json

Example of translation process with a two-letter locale

The translation process for a browser with a two-letter locale of fr (French) follows the same logic as in Example of translation process 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 process 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. The translation process will still work as expected with no loss of functionality, falling back through locales until it finds a translation for each key.

REST API

Create or replace translation configuration

  1. Create an access token for the realm where you want to apply the translation.

  2. Create or replace the translation configuration for each locale:

    Show request 
    $ curl \
--request PUT 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) (2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data-raw '{(4)
    "admin": {
        "sideMenu": {
            "securityQuestions": "Questions de sécurité"
        },
        "overrides": {
            "EmailAddress": "Adresse e-mail",
            "Name": "Nom",
            "Owners": "Les propriétaires",
            "AppLogoURI": "URI du logo de l’application"
        }
    },
    "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",
            "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
        }
    },
    "shared": {
        "sideMenu": {
            "dashboard": "Tableau de bord"
        }
    }
}
'
    1 Replace <tenant-env-fqdn> with the domain of your development environment; for example, openam-mycompany.forgeblocks.com.
    2 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)
    3 Replace <access-token> with the access token.
    4 Replace the example translation configuration with your own translation configuration.
    Show response 
    {
    "_id": "uilocale/fr",
    "admin": {
        "sideMenu": {
            "securityQuestions": "Questions de sécurité"
        },
        "overrides": {
            "EmailAddress": "Adresse e-mail",
            "Name": "Nom",
            "Owners": "Les propriétaires",
            "AppLogoURI": "URI du logo de l’application'"
        }
    },
    "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",
            "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
        }
    },
    "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 be fr.json.

View translation configuration

  1. View the translation configuration using a GET request. You do not need an access token to view the translation configuration because it is publicly accessible.

    Show request 
    $ curl \
--request GET 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) (2)
    1 Replace <tenant-env-fqdn> with the domain of your development environment; for example, openam-mycompany.forgeblocks.com.
    2 Replace <locale> with a locale identifier, such as fr.
    Show response 
    {
    "_id": "uilocale/fr",
    "admin": {
        "sideMenu": {
            "securityQuestions": "Questions de sécurité"
        },
        "overrides": {
            "EmailAddress": "Adresse e-mail",
            "Name": "Nom",
            "Owners": "Les propriétaires",
            "AppLogoURI": "URI du logo de l’application"
        }
    },
    "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",
            "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
        }
    },
    "shared": {
        "sideMenu": {
            "dashboard": "Tableau de bord"
        }
    }
}

    When attempting to view the default en translation, no results are returned. To view the default en translation, learn more in the UI package files specified in View translation configuration.

    If you receive a 404 response, the locale is not defined. To create a locale, learn more in Create or replace translation configuration.

Delete translation configuration

  1. Create an access token for the realm where the translations are applied.

  2. Delete the translation configuration:

    Show request 
    $ curl \
--request DELETE 'https://<tenant-env-fqdn>/openidm/config/uilocale/<locale>' \(1) (2)
--header 'Authorization: Bearer <access-token>' (3)
    1 Replace <tenant-env-fqdn> with the domain of your development environment; for example, openam-mycompany.forgeblocks.com.
    2 Replace <locale> with a locale identifier, such as fr.
    3 Replace <access-token> with the access token.
    Show response 
    {
    "_id": "uilocale/fr",
    "admin": {
        "sideMenu": {
            "securityQuestions": "Questions de sécurité"
        },
        "overrides": {
            "EmailAddress": "Adresse e-mail",
            "Name": "Nom",
            "Owners": "Les propriétaires",
            "AppLogoURI": "URI du logo de l’application"
        }
    },
    "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",
            "UnabletoresumesessionItmayhaveexpired": "Impossible de reprendre la session. Elle a peut-être expiré."
        }
    },
    "shared": {
        "sideMenu": {
            "dashboard": "Tableau de bord"
        }
    }
}