ForgeRock Identity Platform 7.3

Localize end-user and login UIs

You can localize the 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 to 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 the end user’s browser. If none is available, they default to the 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 enduser, login, and shared top-level blocks correspond to the names of the UI packages in GitHub:
2 Key/phrase translation pairs with predefined keys

Most of the key/phrase translation pairs are predefined in the en locale translation files for each package:

You can translate some or all of the keys. To create different translations in the enduser and login blocks for a key from the shared block, you can copy the JSON structure for the shared key into each of the enduser and login blocks, where they override 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 such as underscores stripped out.

These translation pairs with literal keys are designed as a catch-all solution for undefined UI phrases, and for any unlocalized phrases that come directly from the backend servers. The example shows two literal keys that translate the placeholder text from input fields in an authentication journey. Use this approach to translate server output from authentication messages and journey nodes.

Translation pairs with literal keys are currently only available within the login top-level block.

Translation precedence and fall back

The UIs translate each key/phrase pair in a particular order. They determine a primary locale using the requested language from an end user’s browser. If no translation is available for 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 as follows:

  1. Attempt to use the primary fr locale:

    1. Look for the translation key in the configuration for the fr locale, /openidm/config/uilocale/fr.

      This returns HTTP 404 Not Found if the configuration is missing. Refer to Translation 404 responses.

    2. Look for the translation key in any translation files for the fr locale:

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

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

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

  2. Fall back to the default en locale:

    1. Look for the translation key in the configuration for the en local, /openidm/config/uilocale/en.

      This returns HTTP 404 Not Found if the configuration is missing. Refer to Translation 404 responses.

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

One or more 404 responses may display 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.

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

  1. Get an administrator access token.

    To get an access token, open your browser’s developer tools before logging in as an administrator, and examine the response to a request to the access_token endpoint.

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

    Show request 
    curl \
--request PUT 'http://openidm.example.com:8080/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 view the translation configuration as it is publicly accessible.

  1. View the translation configuration using a GET request:

    Show request 
    curl \
--request GET 'http://openidm.example.com:8080/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

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

    Open your browser’s developer tools before logging in to the realm as an administrator, and examine the response to a request to the access_token endpoint.

  2. Delete the translation configuration:

    Show request 
    curl \
--request DELETE 'http://openidm.example.com:8080/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"
        }
    }
}
Copyright © 2010-2024 ForgeRock, all rights reserved.