3.3 Internationalization

Owned by Rod Widdowson
Last updated: Jul 22, 2021
3 min read

Localizing the EDS

The EDS is entirely globalized. This means that in usual operations all text that is displayed to the user can be controlled via the configuration of the DS. Precisely which text is displayed is adjusted as a function of the language and locale of the browser as determined by the EDS.

It is important to understand that the technical underpinnings do not allow the EDS access to the most useful setting (the language setting of the browser itself).

The EDS therefore tries a series of common (but non-standard) techniques to determine the locale of the browser, which is often the locale with which the operating system was installed. From this locale the language can be determined. However this may not be the same as the browser's currently selected preferred language.

If the browser does not respond to any of these techniques, then the default language configured into the EDS is used.

The net result of this is that a user may not see the localization they expected, but will see a localization that is useful to them. See also the Technical Details below.

The messages which can be displayed are defined in the configuration file idpselect_config.js and (from V1.1 onwards idpselect_languages.js which is combined into the minimised source)  as a series of bundles. V1.1 ships with bundles for English, German, Japanese and Brazilian Portuguese.

To extend the EDS for an additional language add the language to the langBundles variable in idpselect_config.js by adding an entry for the appropriate language (for instance "gd" or "fr-ca").   You can modify the language bundle that is shipped with the EDS in the same way.

Note that the EDS will use your language bundles in preference to the shipped language bundles and the most specific language possible. For instance, if the browser reports "en-gb" then the EDS would use a "en-gb" bundle in preference to an "en" bundle. Equally if only a "en-us" bundle is specified then there will be no match and the default language will be used.

IdPs

The DisplayNames of the IdPs are localized and their logos may be localized. Again, the EDS will select according to the browser locale's language, if available, falling back to the default language if the browser language is not available or if no DisplayName for the browser locale's language exists.

Technical Details

When the EDS is initialized, it attempts to determine the locale and language of the browser by consulting navigator.language. If this doesn't exist it then consults navigator.userLanguage. If either of these exist, then they are used as the language of choice.

If this language contains a hyphen (for example "fr-ca" or "en-gb") then the first part is taken as the 'major language'.

From then on all language lookup is done

  1. First from the entire supplied language. (e.g. "fr-ca").  The search is done first in your configured bundles and then the provided bundles.


  2. Then from the 'major language' ("fr")


  3. Then from the default language as configured into the EDS.

This mechanism is used:

  • For the language bundle which describes the static text displayed in the browser. If a required message doesn't exist having followed all three of these options then an error is displayed; this is a configuration error since the language bundles must contain all the messages for the default language.


  • For the IdP Display Name. If an IdP does not have a display name in any of these languages then its entityID is used.


  • For the IdP Logo. If an IdP does not have a logo in the browser language or 'major language' then a logo with no language is chosen. If none of these is present then a logo with the default language is chosen. If there is still no logo, then the defaultLogo is used. Note that the size of the logo is used to determine choice, but this is secondary to the language-driven choice.