Options
All
  • Public
  • Public/Protected
  • All
Menu

Class LocalizationManager

Fully featured translation manager to be used with any application that requires text internationalization.

Hierarchy

  • LocalizationManager

Index

Properties

Methods

Properties

Private _activeBundle

_activeBundle: string = ""

Stores the latest resource bundle that's been used to read a localized value. This is used by default when calling get without a bundle value

Private _activeLocation

_activeLocation: string = ""

Stores the label for the latest location that's been used to read a localized value This is used by default when calling get without a location value

Private _definedLocations

_definedLocations: { bundles: string[]; label: string; path: string }[] = []

Stores all the provided location definitions

Private _filesManager

_filesManager: any = null

A files manager instance used to load the data when paths are from file system.

(Note that FilesManager class is part of the TurboDepot library)

Private _httpManager

_httpManager: HTTPManager | null = null

An http manager instance used to load the data when paths are urls

Private _initialized

_initialized: boolean = false

Tells if the class has been initialized or not

Private _languages

_languages: string[] = []
see

this.languages()

Protected _loadedTranslations

_loadedTranslations: {}

Stores all the loaded localization data by location name, locales, bundle and key

Type declaration

  • [location: string]: {}
    • [locale: string]: {}
      • [bundle: string]: {}
        • [key: string]: string

Private _locales

_locales: string[] = []
see

this.locales()

isBundleMandatory

isBundleMandatory: boolean = false

If set to true, when we call any get method from this class to retrieve a translated text, we will be forced to provide the bundle for the key we are looking for. If set to false, only the key parameter will be required.

missingKeyFormat

missingKeyFormat: string = "$exception"

Defines the behaviour for get(), getStartCase(), etc... methods when a key is not found on a bundle or the bundle does not exist

If this value is empty, all missing keys will return an empty value If this value contains a string, all missing keys will return that string If this value contains a string with some of the following wildcards:

  • $key will be replaced with the key name. For example: get("NAME") will output [NAME] if the key is not found and missingKeyFormat = '[$key]'
  • $exception (This is the default value) will throw an exception with the problem cause description.

wildCardsFormat

wildCardsFormat: string = "{N}"

Wildcards are string fragments that are placed inside the translated texts. Their main purpose is to be replaced at runtime by custom values like for example a user name, a date, a numeric value, etc..

This class helps with this process by including a parameter called 'toReplace' on all .get methods which allows us to specify a string or list of strings that will replace the respective wildcards on the translated text. Each wildcard must follow the format specified here, and contain a numeric digit that will be used to find the replacement text at the 'toReplace' list. For example, if we define $N as the wildcard format, and we have a translation that contains $0, $1, $2, $0 will be replaced with the first element on toReplace, $1 with the second and so.

Note that N is mandayory on the wildcards format and the first index value is 0.

Methods

Private _loadData

  • _loadData(locales: string[], locations: { bundles: string[]; label: string }[], finishedCallback?: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null, progressCallback?: ((completedUrl: string, totalUrls: number) => void) | null): void

  • Auxiliary method used to perform the translation data load

    see

    this.initialize()

    Parameters

    • locales: string[]

      List of locales to load

    • locations: { bundles: string[]; label: string }[]

      A list of locations and respective bundles to be loaded

    • Default value finishedCallback: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null = null

      A method that will be executed once the load ends. An errors variable will be passed to this method containing an array with information on errors that may have happened while loading the data.

    • Default value progressCallback: ((completedUrl: string, totalUrls: number) => void) | null = null

      Executed after each request is performed

    Returns void

Private _loadDataFromUrls

  • _loadDataFromUrls(pathsToLoad: string[], pathsToLoadInfo: any[], finishedCallback?: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null, progressCallback?: ((completedUrl: string, totalUrls: number) => void) | null): void

  • Perform the paths load from urls

    Parameters

    • pathsToLoad: string[]

      list of paths that need to be loaded

    • pathsToLoadInfo: any[]

      original info about the paths to load

    • Default value finishedCallback: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null = null

      method to execute once finished

    • Default value progressCallback: ((completedUrl: string, totalUrls: number) => void) | null = null

      method to execute after each path is loaded

    Returns void

activeBundle

  • activeBundle(): string

  • Get the bundle that is currently being used by default when traslating texts

    Returns string

    The name for the currently active bundle

get

  • get(key: string, bundle?: string, location?: string, toReplace?: string | string[]): string

  • Get the translation for the given key, bundle and location

    Parameters

    • key: string

      The key we want to read from the specified resource bundle and path

    • Default value bundle: string = ""

      The name for the resource bundle file. If not specified, the value that was used on the inmediate previous call of this method will be used. This can save us lots of typing if we are reading multiple consecutive keys from the same bundle.

    • Default value location: string = ""

      In case we have multiple bundles with the same name on different locations, we can set this parameter with the location label to uniquely reference the bundle and resolve the conflict. If all of our bundles have different names, this parameter can be ignored. Just like the bundle parameter, this one is remembered between get() calls.

    • Default value toReplace: string | string[] = []

      A list of values that will replace the wildcards that are found on the translated text. Each wildcard will be replaced with the element whose index on the list matches it. Check the documentation for this.wildCardsFormat property to know more about how to setup wildcards.

    Returns string

    The localized text

getAllLowerCase

  • getAllLowerCase(key: string, bundle?: string, location?: string, toReplace?: string | string[]): string

  • Get the translation for the given key and bundle as an all lower case string

    see

    LocalizationManager.get

    see

    StringUtils.formatCase

    Parameters

    • key: string
    • Default value bundle: string = ""
    • Default value location: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

getAllUpperCase

  • getAllUpperCase(key: string, bundle?: string, location?: string, toReplace?: string | string[]): string

  • Get the translation for the given key and bundle as an all upper case string

    see

    LocalizationManager.get

    see

    StringUtils.formatCase

    Parameters

    • key: string
    • Default value bundle: string = ""
    • Default value location: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

getFirstUpperRestLower

  • getFirstUpperRestLower(key: string, bundle?: string, location?: string, toReplace?: string | string[]): string

  • Get the translation for the given key and bundle as a string with the first character as Upper case and all the rest as lower case

    see

    LocalizationManager.get

    see

    StringUtils.formatCase

    Parameters

    • key: string
    • Default value bundle: string = ""
    • Default value location: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

getStartCase

  • getStartCase(key: string, bundle?: string, location?: string, toReplace?: string | string[]): string

  • Get the translation for the given key and bundle as a string with all words first character capitalized and all the rest of the word with lower case

    see

    LocalizationManager.get

    see

    StringUtils.formatCase

    Parameters

    • key: string
    • Default value bundle: string = ""
    • Default value location: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

initialize

  • initialize(locationsLoader: any, locales: string[], locations: { bundles: string[]; label: string; path: string }[], finishedCallback?: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null, progressCallback?: ((completedUrl: string, totalUrls: number) => void) | null): void

  • Performs the initial data load by looking for resource bundles on all the specified locations. All the translations will be loaded for each of the specified locales.

    Calling this method is mandatory before starting to use this class.

    Parameters

    • locationsLoader: any

      An instance of HTTPManager or FilesManager that will be used to load the provided locations. If we are working with paths that are urls, we will pass here an HTTPManager. If we are working with file system paths, we will pass a FilesManager. (Note that FilesManager class is part of the TurboDepot library)

    • locales: string[]

      List of languages for which we want to load the translations. The list also defines the preferred translation order when a specified key is not found for a locale.

    • locations: { bundles: string[]; label: string; path: string }[]

      A list (sorted by preference) where each item defines a translations location and must have three properties: - label: A name that will be used to reference the location - path: A relative or absolute string that defines a location where resourcebundles reside. It must contain some wildcards: - $locale wildcard will be replaced by each specific locale when trying to reach a path - $bundle wildcard will be replaced by each specific bundle name when trying to reach a path Example1: 'myFolder/$locale/$bundle.txt' will resolve to 'myFolder/en_US/Customers.txt' when trying to load the Customers bundle for US english locale. Example2: 'myFolder/$bundle_$locale.properties' will resolve to 'myFolder/Customers_en_US.properties' when trying to load the Customers bundle for US english locale. - bundles: The list of bundles to be loaded from the specified path

    • Default value finishedCallback: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null = null

      A method that will be executed once the initialization ends. An errors variable will be passed to this method containing an array with information on errors that may have happened while loading the data.

    • Default value progressCallback: ((completedUrl: string, totalUrls: number) => void) | null = null

      A method that can be used to track the loading progress when lots of bundles and locales are used.

    Returns void

    void

isInitialized

  • isInitialized(): boolean

  • Check if the class has been correctly initialized

    Returns boolean

isLanguageLoaded

  • isLanguageLoaded(language: string): boolean

  • Checks if the specified 2 digit language is currently loaded for the currently defined bundles and paths.

    Parameters

    • language: string

      A language to check. For example 'en'

    Returns boolean

    True if the language is currently loaded on the class, false if not.

isLocaleLoaded

  • isLocaleLoaded(locale: string): boolean

  • Checks if the specified locale is currently loaded for the currently defined bundles and paths.

    Parameters

    • locale: string

      A locale to check. For example 'en_US'

    Returns boolean

    True if the locale is currently loaded on the class, false if not.

languages

  • languages(): ReadonlyArray<string>

  • A list of strings containing the languages that are used by this class to translate the given keys, sorted by preference. Each string is formatted as a 2 digit language code, like: en, fr

    This list is the same as the locales() one, but containing only the language part of each locale (the first two digits)

    see

    this.locales()

    Returns ReadonlyArray<string>

loadBundles

  • loadBundles(bundles: string[], location?: string, finishedCallback?: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null, progressCallback?: ((completedUrl: string, totalUrls: number) => void) | null): void

  • Loads on the specified location the translation data for the specified bundles. This method can only be called after the class has been initialized in case we need to refresh or add more bundles to an already loaded location.

    see

    this.initialize()

    Parameters

    • bundles: string[]

      List of bundles to load from the specified location

    • Default value location: string = ""

      The label for an already defined location. The extra bundles translation data will be added to the already loaded ones. If not defined, the current active location will be used.

    • Default value finishedCallback: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null = null

      A method that will be executed once the load ends. An errors variable will be passed to this method containing an array with information on errors that may have happened while loading the data.

    • Default value progressCallback: ((completedUrl: string, totalUrls: number) => void) | null = null

      A method that can be used to track the loading progress when lots of bundles and locales are used.

    Returns void

    void

loadLocales

  • loadLocales(locales: string[], finishedCallback?: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null, progressCallback?: ((completedUrl: string, totalUrls: number) => void) | null): void

  • Adds extra locales to the end of the list of currently active locales and load its related translation data.

    This method can only be called after the class has been initialized in case we need to load the translations for more languages. If any of the provided new locales is already loaded, its translation data will be refreshed

    Parameters

    • locales: string[]

      List of languages for which we want to load the translations. The list will be appended at the end of any previously loaded locales and included in the preferred translation order. The translation data will be loaded from all the currently defined locations.

    • Default value finishedCallback: ((errors: { errorCode: number; errorMsg: string; path: string }[]) => void) | null = null

      A method that will be executed once the load ends. An errors variable will be passed to this method containing an array with information on errors that may have happened while loading the data.

    • Default value progressCallback: ((completedUrl: string, totalUrls: number) => void) | null = null

      A method that can be used to track the loading progress when lots of bundles and locales are used.

    Returns void

    void

locales

  • locales(): ReadonlyArray<string>

  • A list of strings containing the locales that are used by this class to translate the given keys, sorted by preference. Each string is formatted as a standard locale code with language and country joined by an underscore, like: en_US, fr_FR

    When a key and bundle are requested for translation, the class will check on the first language of this list for a translated text. If missing, the next one will be used, and so. This list is constructed after the initialize or loadLocales methods are called.

    example:

    After loading the following list of locales ['en_US', 'es_ES', 'fr_FR'] if we call localizationManager.get('HELLO', 'Greetings') the localization manager will try to locate the en_US value for the HELLO tag on the Greetings bundle. If the tag is not found for the specified locale and bundle, the same search will be performed for the es_ES locale, and so, till a value is found or no more locales are defined.

    Returns ReadonlyArray<string>

Protected parseJson

  • parseJson(jsonString: string): {}

  • Auxiliary method that can be overriden when extending this class to customize the parsing of Json formatted resource bundles

    Parameters

    • jsonString: string

      An object with the read resourcebundle json string

    Returns {}

    • [key: string]: string

Protected parseProperties

  • parseProperties(propertiesString: string): {}

  • Auxiliary method that can be overriden when extending this class to customize the parsing of Java properties formatted resource bundles

    Parameters

    • propertiesString: string

      A string containing the read resourcebundle java properties format string

    Returns {}

    • [key: string]: string

primaryLanguage

  • primaryLanguage(): string

  • Get the first language from the list of loaded locales, which is the currently used to search for translated texts.

    Returns string

    The 2 digit language code that is defined as the primary one. For example: en, es, ..

primaryLocale

  • primaryLocale(): string

  • Get the first locale from the list of loaded locales, which is the currently used to search for translated texts.

    Returns string

    The locale that is defined as the primary one. For example: en_US, es_ES, ..

setActiveBundle

  • setActiveBundle(bundle: string): void

  • Define the bundle that is used by default when no bundle is specified on the get methods

    Parameters

    • bundle: string

      A currently loaded bundle to be used as the active one

    Returns void

    void

setLocalesOrder

  • setLocalesOrder(locales: string[]): void

  • Change the loaded locales translation preference order. The same locales that are currently loaded must be passed but with a different order to change the translation priority.

    Parameters

    • locales: string[]

      A list with the new locales translation priority

    Returns void

    void

setPrimaryLanguage

  • setPrimaryLanguage(language: string): void

  • Define the 2 digit language that will be placed at the front of the currently loaded locales list (moving all the others one position to the right).

    This will be the first language to use when trying to get a translation.

    Parameters

    • language: string

      A 2 digit language code that matches with any of the currently loaded locales, which will be moved to the first position of the loaded locales list. If the specified language does not match with a locale that is currently loaded, an exception will happen.

    Returns void

    void

setPrimaryLanguages

  • setPrimaryLanguages(languages: string[]): void

  • Moves the locales that match the specified languages to the beginning of the locales list. Works the same as setPrimaryLocales() but with a list of the 2 digit language codes that match the respective locales.

    see

    LocalizationManager.setPrimaryLocale()

    see

    LocalizationManager.setPrimaryLanguage()

    Parameters

    • languages: string[]

      A list of 2 digit language codes to be moved to the beginning of the translation priority. If any of the specified languages does not match with a locale that is currently loaded, an exception will happen.

    Returns void

    void

setPrimaryLocale

  • setPrimaryLocale(locale: string): void

  • Define the locale that will be placed at the front of the currently loaded locales list (moving all the others one position to the right).

    This will be the first locale to use when trying to get a translation.

    Parameters

    • locale: string

      A currently loaded locale that will be moved to the first position of the loaded locales list. If the specified locale is not currently loaded, an exception will happen.

    Returns void

    void

setPrimaryLocales

  • setPrimaryLocales(locales: string[]): void

  • Moves the specified locales to the beginning of the locales list. This also alters the translation priority by setting the first provided locale as the most prioritary, the second as the next one and so.

    This method basically works exactly the same way as setPrimaryLocale but letting us add many locales at once.

    see

    LocalizationManager.setPrimaryLocale()

    Parameters

    • locales: string[]

      A list of locales to be moved to the beginning of the translation priority. First locales item will be the prefered locale for translation, second will be the next one in case some key is not translated for the first one and so. If any of the specified locales is not currently loaded, an exception will happen.

    Returns void

    void

Generated using TypeDoc