Localization Overview

Localization is a process by which you can customize the various strings used throughout the applications and interfaces of EmpowerID. Each label of an EmpowerID interface as well as the email notifications that EmpowerID sends has properties and objects associated with it that can be bound to a particular string of text and each EmpowerID Person has a property that determines which string version they see within an EmpowerID application, page, or email notification. 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.
  • Localized Texts - Localized Texts are objects used for grouping together a set of EmpowerID texts categorically related to one another. Localized Texts are not texts themselves; they 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, one of the Localized Text objects in EmpowerID is the PasswordManagerQuestions Localized Text object. This particular Localized Text object holds each Password Manager enrollment question available to your users when enrolling for the EmpowerID self-service password reset function.
  • Localized Text Entries - Localized Text Entries are children of the above mentioned Localized Text objects and are the actual texts used throughout the interfaces of each EmpowerID application, page, or email. The strings associated with a Localized Text Entry is, generally speaking, the default text that appears to users without a specific locale set on their EmpowerID Person. Each Localized Text Entry can have any number of translated versions or "Localized Entries" to support each locale in use by your organization. Each Localized Entry for a given Localized Text Entry 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 food?" As the default value, this text is what a user without a specific locale set on their person sees. However, this question has several different translations available, one of which is a Spanish version that reads "¿Cuál es su comida favorita?" This translation is a Localized Entry of the default "What is your favorite food?" Localized Text Entry and is differentiated from it by the es-ES locale applied to it.
  • Locale Key Entry - EmpowerID creates a Locale Key Entry for each Localized Text Entry object in the EmpowerID Identity Warehouse. Locale Keys are a concatenation of a Localized Text object and a default Localized Text Entry contained within the Localized Text object. EmpowerID uses Locale Key Entries to link Localized Entries with their default Localized Text Entry, replacing the default Localized Text Entry with the appropriate Localized Entry for users with differing locales. For example, the Locale Key Entry for the "What is your favorite food?" Localized Text Entry is "PasswordManagerQuestions_What is your favorite food?" As mentioned above, this Localized Text Entry has a Spanish Localized Entry with an "es-ES" locale. When a user with that same locale logs in to EmpowerID, EmpowerID loads the Locale Key Entry for the Localized Text Entry and checks to see if a Localized Entry with an "es-ES" locale exists. If EmpowerID finds that the Localized Entry exists, it replaces the Locale Key Entry with that Localized Entry. In this way, a user with the "es-ES" locale will see "¿Cuál es su comida favorita?", while a user without a specific locale set on their person will see the default value.

  • Preferred Language - Preferred Language is a property that you can set for each EmpowerID Person to link that person to a specific locale and the Localized Entries of any Localized Text Entries available for that locale. If this property is not set to a specific locale, the person will see the default Localized Text Entry.

    Visually, the relationship between these objects can be represented in the following way:

    Preferred languages can be set for each EmpowerID Person via one of the following workflows:

    • CreatePersonSimple - Running this workflow allows you to set the Preferred Language for a user when creating their EmpowerID Person object.
    • CreatePersonAndAccount - Running this workflow allows you to set the Preferred Language for a user when creating both their EmpowerID Person object and external directory user account.
    • EditPersonDemographics - Running this workflow allows you to set the Preferred Language for an existing EmpowerID Person object.
    • PersonEdit - Running this workflow allows you to set the Preferred Language for an existing EmpowerID Person object.

    Running one of the above workflows opens a form with a Preferred Language drop-down populated with the Display Names of the locales that exist in the Collection of Locales and Languages in Configuration Manager ("French" is the Display Name for the "fr-FR" locale). The image below shows the Preferred Language drop-down in the Edit Person form of the PersonEdit workflow Delegated users can set this property for any EmpowerID Person. Once the Preferred Language is set for an EmpowerID Person, that person will see all EmpowerID user interface elements that have Localized Entries with matching locales.

    The Localized Entries applied to the EmpowerID Login screen for the EmpowerID Web application is set by the language settings applied to the browser on the local machine. Once a user logs in, the Localized Entries applied to the EmpowerID web pages will match the Preferred Language settings on that user's EmpowerID Person object.
    EmpowerID uses a number of criteria to determine what language should be applied to the pages of the EmpowerID Web application. These criteria and their precedence are as follows:
    1. Language Query string parameter - A language query string parameter can be appended to the base URL for any page associated with the Web application to force the Web application to display that page in a given language. For example, if you want to display the pages of the Web application in a specific language, you append the URL for the Home page with lang=<ISO 639 culture code>-<ISO 3166 subculture code>, as in https://sso.empowerid.com/EmpowerIDV5/?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 appropriate locale. EmpowerID will then append 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 tile will be displayed in the language associated with the language query string parameter.
    2. Person's Preferred Language - If a language query string parameter is not used, EmpowerID displays all localized entries in the Preferred Language set on the Person.
      3. An exception to this rule is the Login page of the EmpowerID Web application. If a language query string parameter is not used, EmpowerID displays the text of the page to the user based on the language settings applied to the browser on their local machine. If the preferred language of the Person logging in differs from the browser's language setting, EmpowerID will display the pages in that person's preferred language once they have authenticated.
    3. Browser Language Settings - Finally, if a a language query string parameter is not used and the user does not have a Preferred Language set on their Person object, EmpowerID displays the text of the page to the user in accordance with the language settings applied to their browser.


Localization and Stored Procedures

EmpowerID includes a number of stored procedures related to localizing EmpowerID. These stored procedures are as follows:

  • Z_RefreshCatalogLocaleDataKeys - Running this stored procedure creates a Localized Key Entry object for the title and description of any request items in the Service Catalog that are placed in the EmpowerID Workflow Catalog category as well as sets the default value of each.
  • Z_RefreshGridTypeLocaleDataKeys - This stored procedure reads the XML for each grid type defined in the EmpowerID Identity Warehouse, adding or removing columns from the UI in accordance with the XML file for each grid type. Additionally, _Z_RefreshGridTypeLocaleDataKeys_ creates a Localized Key Entry object in the Locale Key Entry table of the Identity Warehouse for each Locale Key Entry it discovers in a Grid Type Definition XML file not currently in that table, renames any default values that have changed in the grid as well as deletes any keys no longer in the grid XML.
  • Z_RefreshRbacObjectsLocaleDataKeys - Running this stored procedure allows you to create a Locale Key Entry object for a specific Rbac object by passing the component name for that object in to the stored procedure.
  • Z_RefreshResourceTypeLocaleDataKeys - Running this stored procedure creates a Localized Key Entry object for any resource types currently without one.
  • Z_RefreshResourceTypeRoleLocaleDataKeys - Running this stored procedure creates a Localized Key Entry object for any Resource Role type currently without one.
  • Z_RefreshRibbonLocaleDataKeys - This stored procedure reads the XML for each ribbon defined in the EmpowerID Identity Warehouse and creates a Localized Key Entry object for each tab, group or button in a ribbon currently without one. This allows you to localize any new menus you create in Workflow Studio.