Localizing the IAM Shop

Owned by Phillip Hanegan
Last updated: Jul 09, 2024
4 min read

Localization is the process of customizing the strings used in EmpowerID applications and interfaces. This process allows you to set up different language locales and also customize locales for different tenants. Any visible text, from labels to email notifications, has properties and objects associated with it that you can bind to a localized string of text.

Localization Components

These objects and properties combine within EmpowerID to allow users with different language preferences to see the texts used throughout EmpowerID in their preferred language at runtime. The localization properties and objects include the following:

Locales

Locales are a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. These objects are used within EmpowerID as identifier values for linking together a person in EmpowerID with any localized strings and emails created for a specific language group and culture. For example, the version of French expressed in France is identified by "fr-FR," while the version of French expressed in Quebec, Canada, is identified by "fr-CA." Each locale is its own object in the EmpowerID Identity Warehouse with its own unique identifier, the LocaleID. This identifier links an EmpowerID Person to a specific localized version of EmpowerID.

Sets

Sets (LocaleResourceSet in the database) are objects used for grouping together a set of texts categorically related to one another. Sets are simply containers used to hold the strings displayed throughout the interfaces of each EmpowerID application, page, or email, logically representing the purpose of those strings. For example, the Set for the IT Shop is the IT Shop Microservice App set, which holds each localized text entry linked to the IAM Shop.

Localized Strings

Localized Strings (LocaleKeyEntry in the database) are children of the above-mentioned Sets and are the actual texts used throughout the interfaces of each EmpowerID application, page, or email. The default value of the strings is the text that appears to users without a specific locale set on their EmpowerID Person. Each Localized String can have any number of translated versions to support each locale in use by your organization. For instance, one of the default Password Manager enrollment questions is "What is your favorite beverage?" This question has numerous translations available, such as the German version "Was ist dein Lieblingsgetränk?”

Locale Key Entry

EmpowerID creates a Locale Key Entry for each Localized String in the EmpowerID Identity Warehouse. Locale Key Entries link Localized Strings with their default value, replacing the default value with the appropriate translation (LocaleData) for users with differing locales. For example, the Locale Key Entry Name for the "What is your favorite beverage?" Localized String is "PasswordManagerQuestions_Whatisyourfavoritebeverage?" EmpowerID uses this entry to load the appropriate translation based on the user's locale.

Determining Language in EmpowerID

 EmpowerID uses several criteria to determine what language to apply to the pages of the web application:

Language Query String Parameter

You can append a language query string parameter to the base URL for any page in the web application to force it to display that page in that language. To display all web application pages in a specific language, append lang=<ISO 639 culture code>-<ISO 3166 subculture code> to the Home page URL. For example, https://sso.empowerid.com/UI/?lang=fr-fr will display the pages in French (France). EmpowerID appends this parameter to each page until it is removed from the URL or the user session ends.

Person's Preferred Language

If a language query string parameter is not used, EmpowerID displays all localized entries in the Preferred Language chosen by the logged-in Person.

Browser Language Settings

If no language query string parameter is used and the Person is not logged in, EmpowerID displays the text of the page in accordance with the language settings applied to their browser.

IT Shop Locale Keys

A locale key represents each text string in the EmpowerID UI. Developers use the locale key for titles, descriptions, and labels in the UI, and the Localized Text in the EmpowerID UI allows you to customize the default text and add translations for any supported languages.

Creating Locale Keys for the IT Shop

When creating locale keys for the IT Shop, follow these guidelines:

  • All locale keys should follow the pattern: {ResourceSetName}_{NamespaceName}_{key}, e.g., ITShop_ApplicationRoles_HighLevelClassification.

  • Each microservice has its own resource set, and all resource sets have a namespace called Common.

  • Locale key namespaces are separated based on product areas, such as On-Boarding, Manage Access, and Resource Types (e.g., Application Roles, Business Roles, Azure Licenses).

  • All locale keys should have a default value to ensure a fallback if no translations are available.

Viewing Default Locale Key Values

You can view the default locale key values for the IAM Shop by appending ?debugLocalization=true to the URL for the IAM Shop Portal, as shown in the image below.

image-20240709-154112.png