I18nManager

I18nManager ⇐ `Class`

Kind: global class
Extends: Class
Warning: private subtags must be 8-letters long maximum
Singleton:
See

https://tools.ietf.org/html/bcp47
https://tools.ietf.org/html/rfc5646
https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes

Properties

Name	Type	Description
defaultLocale	`string` \| `null`	The id of the default locale - Use by default the first item of the "locales" array defined in the profile - example "en-GB"
availableLocales	`Array.<string>`	List of the available Locales, as defined in the profile "locales" array, that can be used to call the setLocale method - example ["en-GB", "fr-FR"]
locale	`LocaleString`	Current locale data containing all the string translations
loadedLocales	`Object.<string, LocaleString>`	Cache of All the loaded locales
stringReplacement	`Object`	Parameters to be used during string replacement
stringReplacement.startDelimiter	`string`	First part of the RegEx to be used for string replacement. Should be a string and not a substring of a regex
stringReplacement.endDelimiter	`string`	Last part of the RegEx to be used for string replacement. Should be a string and not a substring of a regex
stringReplacement.firstIndex	`number`	First number to be used for string replacement
userSettingsService	`$UserSettingsService`

I18nManager ⇐ Class
- new I18nManager()
- instance
  - .getLocaleId() ⇒ object
  - .getLanguageIsoCode([variant]) ⇒ string | null
  - .getStr(key) ⇒ string
  - .loadLocale(localeId) ⇒ Promise.<LocaleString, LocaleLoadError>
  - .setLocale(localeId) ⇒ Promise.<LocaleChangeSuccess, LocaleLoadError>
  - ._initialize() ⇒ Promise.<LocaleChangeSuccess, LocaleLoadError>
  - “localeLoaded”
  - “localeChanged”
- static

I18nManager()

This class represents the i18n manager.

It contains the current language locale and let you get values from it. Locale translations are loaded from the resolved LocalString{id}.json files which are generated from the “i18n” JSON files based on the profile locales selection (ex: “locales”: [“en-GB”, “fr-FR”]).

Initial language is set to the locale defined via the app.config profile i18nManager.defaultLocale, or by default to the first selected locale in the “locales” array.

Locales identifiers are based on the “RFC 5646: Tags for Identifying Languages” standard itself referenced by “BCP 47: Best Current Practice - Tags for Identifying Languages”

The expected supported subset is in ABNF syntax:


langtag       = language
                  ["-" region]
                  ["-" privateuse]

language      = 2*3ALPHA            ; shortest ISO 639

region        = 2ALPHA              ; ISO 3166-1 code

privateuse    = "x" 1*("-" (1*8alphanum))

https://tools.ietf.org/html/rfc5646#section-2.1

Example

* "en-GB"
* "fr-FR"
* "fr-FR-x-project"
* "fr-FR-x-timeless-project"

getLocaleId() ⇒ `object`

Get the current locale (language/country) id.

Kind: instance method of I18nManager
Returns: object - Returns the current locale id if a locale is defined null else.

getLanguageIsoCode([variant]) ⇒ `string` | `null`

Get a specific ISO language code variant representing the current locale

Possible variants are:

$I18nManager.ISO_639_1: 2-letters ISO-639-1 language code
$I18nManager.ISO_639_2: 3-letters ISO-639-2 language code (alias to ISO_639_2_T)
$I18nManager.ISO_639_2_T: 3-letters ISO-639-2 “terminological” language code
$I18nManager.ISO_639_2_B: 3-letters ISO-639-2 “bibliographic” language code
$I18nManager.ISO_639_3: 3-letters ISO-639-3 language code (extends ISO-639-2 T)

Kind: instance method of I18nManager
Warning: Returns null if the variant is not available for this locale
Throw: Error if the variant

Param	Type	Description
[variant]	`string`	constant representing the ISO format (ISO_639_2_T, ISO_639_2_B, ..)

getStr(key) ⇒ `string`

Get a locale string value

Kind: instance method of I18nManager
Returns: string - Returns the value corresponding to the key parameter. If the key is not found or no bundle is defined, returns the key. If the message contains parameters (ie. %x), it replaces them with function arguments.

Param	Type	Description
key	`string`	The key to look for in the bundle.

Example

I18nManager.getStr(test, "Mr Smith", "Mrs Smith");
         => test : "Hello %1 and %2 !"
         => returns : "Hello Mr Smith and Mrs Smith !";

loadLocale(localeId) ⇒ `Promise.<LocaleString, LocaleLoadError>`

Load all the required definitions (translations, Date formats, …) of a Locale.

The locale Identifiers is based on the “RFC 5646: Tags for Identifying Languages” standard

Kind: instance method of I18nManager
Emits: localeLoaded
Warning: this do not change the current locale but just load the locale data in the cache if not already loaded

Param	Type	Description
localeId	`string`	The locale id corresponding to the locale we want to load.

Example

i18nManager.loadLocale('en-GB').then(doSomething);
  i18nManager.loadLocale('en-GB-x-timeless').then(doSomething);
  i18nManager.loadLocale('en-GB-x-timeless-project').then(doSomething);

For more information on the locale identifier format, see [I18nManager](#I18nManager)

setLocale(localeId) ⇒ `Promise.<LocaleChangeSuccess, LocaleLoadError>`

Change the language and locale settings of the application

May load the corresponding Locale definitions (and fire a “localeLoaded” event) if not already in the cache.

The locale Identifiers is based on the “RFC 5646: Tags for Identifying Languages” standard

Kind: instance method of I18nManager
Emits: localeChanged
Warning: this do not change the current locale but just load the locale data in the cache if not already loaded

Param	Type	Description
localeId	`string`	The locale id of the language we want to change to.

Example

i18nManager.loadLocale('en-GB').then(doSomething);
  i18nManager.loadLocale('en-GB-x-timeless').then(doSomething);
  i18nManager.loadLocale('en-GB-x-timeless-project').then(doSomething);

For more information on the locale identifier format, see [I18nManager](#I18nManager)

_initialize() ⇒ `Promise.<LocaleChangeSuccess, LocaleLoadError>`

I18nManager initialization

Activate the locale set in the userSettingsService If no locale is set in userSettingsService, or if it’s not available for the current profile, then activate the default locale

Kind: instance method of I18nManager
Emits: localeChanged
Access: protected

“localeLoaded”

Fired when a locale definition (Strings, Date format, …) has been loaded

Kind: event emitted by I18nManager
Properties

Name	Type	Description
localeId	`string`	The id of the loaded locale.

“localeChanged”

Fired when the current UI locale has been changed

Kind: event emitted by I18nManager
Properties

Name	Type	Description
localeId	`string`	The id of the new current locale.
oldLocaleId	`string`	The id of the previous locale.