Overview of IAM Shop Localization

Localization is the process of customizing the strings used in EmpowerID applications and interfaces. As the word "localizing" suggests, you can set up different language locales, but you can also set up different 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.

These objects and properties combine within EmpowerID to allow users with different languages preferences to see the texts used throughout EmpowerID in that 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, such as the version of French expressed in France or the version of French expressed in Quebec, Canada. Each of these cultures has a separate ISO convention for differentiating the nuances of the language spoken by each culture. The ISO convention for the French language in France is "fr-FR" while the ISO convention for the same language in Canada is "fr-CA." Each locale is its own object in the EmpowerID Identity Warehouse with its own unique identifier, the LocaleID. This identifier is what EmpowerID uses to link 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 in a manner that logically represents the purpose of those strings. For example, the Set for the IT Shop is the IT Shop Microservice App set. This Set holds each localized text entry linked to the IT 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. Each translated version for a given Localized String is differentiated from one another by the locale assigned to it. For example, one of the default Password Manager enrollment questions shipped by EmpowerID is "What is your favorite beverage?" As the default value, this text is what a user without a specific locale set on their person sees. However, this question has numerous translations available (LocaleData records), one of which is a German version that reads " Was ist dein Lieblingsgetränk?” This translation is a LocaleData object in the database for the default "What is your favorite food?" Localized String object and is differentiated from it by the de-DE locale applied to it.

• Locale Key Entry: EmpowerID creates a Locale Key Entry for each Localized String in the EmpowerID Identity Warehouse. EmpowerID uses Locale Key Entries to 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?" As mentioned above, this Localized Text Entry has a German translation with a "de-DE" locale. When a user with that same locale logs in to EmpowerID, EmpowerID loads the Locale Key Entry for the Localized String and checks to see if a LocaleData record with a "de-DE" locale exists. If EmpowerID finds that the record exists, it replaces the default text for the Locale Key Entry with the Online Translation value for the record. In this way, a user with the "de-DE" locale will see “Was ist dein Lieblingsgetränk?", while a user without a specific locale set on their person will see the default value.

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 pages of the Web application in a specific language, append the following to the Home page URL: lang=<ISO 639 culture code>-<ISO 3166 subculture code>. For example: https://sso.empowerid.com/UI/?lang=fr-fr where sso.empowerid.com is the FQDN of the EmpowerID Web server in your environment, and fr-fr represents the ISO settings for the locale. EmpowerID then appends that parameter to each page of the Web application until it is removed from the URL or the user session ends. Thus, searches for people as well as any pages opened by clicking on an action link are displayed in the language associated with the language query string parameter.

• 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 
  Finally, if no language query string parameter is used and the Person is not logged in, EmpowerID displays the text of the page to the user in accordance with the language settings applied to their browser.

About the IT Shop Locale Keys

Each text string that you see in the EmpowerID UI is represented by a locale key. 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 to add translations for any languages you support. 

The default value of a localized string is what appears by default, in the en, or English locale.

When creating locale keys for the IT Shop, the below points need to be observed:

• All locale keys should follow the same patern. The convention for locale keys is
  {ResourceSetName}_{NamespaceName}_{key}, e.g., ITShop_ApplicationRoles_HighLevelClassification.

• Each microservice has it own resource set and all resource sets have a namespace called Common. The locale key namespaces are not specifically linked to different pages; they are separated based on the areas of the product. The IT Shop has On-Boarding, Manage Access, and Resource Types (Application Roles, Business Roles, Azure Licenses, Azure Admin Roles, and Management Roles), so these are the namespace values.

• All locale keys should have a default value so that if no translations are available, the default value can be used.