Red Hat SummitQuesto contenuto non è disponibile nella lingua selezionata.
Chapter 3. Localization
Learn how to localize strings in the UIs.
Red Hat build of Keycloak supports localized text throughout all user interfaces.
Prerequisites
-
You enable internationalization for a realm in the
Realm settingssection of the Admin Console. See Enabling internationalization.
3.1. Localizing messages in a theme
Text in the templates is loaded from message bundles. When a theme extends another theme, the child theme inherits all messages from the parent’s message bundle. You can override individual messages by adding <THEME TYPE>/messages/messages_en.properties to your theme.
For example, to replace Username on the login form with Your Username for the mytheme, create the file themes/mytheme/login/messages/messages_en.properties with the following content:
usernameOrEmail=Your Username
Within a message, values like {0} and {1} are replaced with arguments when the message is used. For example {0} in Log in to {0} is replaced with the name of the realm.
Texts of these message bundles can be overwritten by realm-specific values, which are manageable by the UI and API.
Each theme can have a locale specific description in the message key theme.<theme-name>.<type>.description. For example, use the key theme.keycloak.v3.account.description to provide a description for the keycloak.v3 theme for the Account Console. As usual, the English message will be the fallback for all other languages.
3.2. Adding a language to a theme
Procedure
-
Create the file
<THEME TYPE>/messages/messages_<LOCALE>.propertiesin the directory of your theme. The<LOCALE>follows the conventions of ResourceBunndle#getBundle. Add this file to the
localesproperty in<THEME TYPE>/theme.properties. For a language to be available to users in a realm, the login, account, and email theme types must support the language, so you need to add your language for those theme types.For example, to add Norwegian translations to the
mythemetheme, create the filethemes/mytheme/login/messages/messages_no.propertieswith the following content:usernameOrEmail=Brukernavn password=PassordIf you omit a translation for messages, those messages appear in English.
Edit
themes/mytheme/login/theme.propertiesand add:locales=en,no-
Make the same changes to the
accountandemailtheme types. To make these changes, createthemes/mytheme/account/messages/messages_no.propertiesandthemes/mytheme/email/messages/messages_no.properties. If you leave these files empty, English messages appear. -
Copy
themes/mytheme/login/theme.propertiestothemes/mytheme/account/theme.propertiesandthemes/mytheme/email/theme.properties. Add a translation for the language selector by adding a message to the English translation. Add the following to
themes/mytheme/account/messages/messages_en.propertiesandthemes/mytheme/login/messages/messages_en.properties:locale_no=Norsk
By default, message properties files should be encoded using UTF-8. Red Hat build of Keycloak falls back to ISO-8859-1 handling if it cannot read the contents as UTF-8. Unicode characters can be escaped as described in Java’s documentation for PropertyResourceBundle.
To simplify migration to the new language codes zh-Hant and zh-Hans, the classloader and folder based themes pick up for the old language codes zh-TW and zh-CN also the files messages_zh_Hant.properties and messages_zh_Hant.properties. Entries in messages_zh_Hant.properties take precedence over entries in messages_zh_TW.properties, and entries in messages_zh_Hans.properties take precedence over entries in messages_zh_CN.properties.
3.3. Overriding localized text for an entire realm
You also have the option to declare translations that take effect for an entire realm. You specify key/value pairs in the realm settings. Any key specified in this way overrides the key/value pairs deployed with a theme.
In most cases, using realm overrides is not the recommended way to achieve localization in Red Hat build of Keycloak. Consider carefully if you want every theme in your realm to use a key/value pair declared as a realm override.
Procedure to add a realm override
- Log into the Admin Console.
- Select your realm.
- Click Realm Settings from the menu.
- Click on the Localization tab.
- Click on the Realm overrides subtab.
- Select a language from the option list.
- Click Add translation.
- Create a key/value pair from the modal dialog.
Notice another subtab called Effective message bundles. This subtab provides a tool to query key/value pairs for a combination of theme, language, and theme type. You can use this tool to test and make sure your realm overrides took effect.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}