Options
All
  • Public
  • Public/Protected
  • All
Menu

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

Hierarchy

  • LocalizationManager

Index

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 _activePath

_activePath: string = ""

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

Private _filesManager

_filesManager: any = null

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

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 _loadedData

_loadedData: object

Stores all the loaded localization data by path, bundle and locales

Type declaration

  • [path: string]: object
    • [locale: string]: object
      • [bundle: string]: object
        • [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[], bundles: object[], finishedCallback?: function | null, progressCallback?: function | null): void
  • Auxiliary method used by the initialize and load methods to perform the data load for the locales and bundles

    see

    this.initialize()

    Parameters

    • locales: string[]

      List of locales to load

    • bundles: object[]

      Information relative to paths and the bundles they contain

    • Default value finishedCallback: function | 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: function | null = null

      Executed after each request is performed

    Returns void

Private _loadDataFromUrls

  • _loadDataFromUrls(pathsToLoad: string[], pathsToLoadInfo: any[], finishedCallback?: function | null, progressCallback?: function | 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: function | null = null

      method to execute once finished

    • Default value progressCallback: function | 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, path?: string, toReplace?: string | string[]): string
  • Get the translation for the given key, bundle and path

    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 path: string = ""

      In case we have multiple bundles with the same name on different paths, we can set this parameter with the path value 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, path?: 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 path: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

getAllUpperCase

  • getAllUpperCase(key: string, bundle?: string, path?: 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 path: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

getFirstUpperRestLower

  • getFirstUpperRestLower(key: string, bundle?: string, path?: 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 path: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

getStartCase

  • getStartCase(key: string, bundle?: string, path?: 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 path: string = ""
    • Default value toReplace: string | string[] = []

    Returns string

    The localized and case formatted text

initialize

  • initialize(pathsManager: any, locales: string[], bundles: object[], finishedCallback?: function | null, progressCallback?: function | null): void
  • Performs the initial data load by looking for resource bundles on all the specified paths. All the translations will be loaded for each of the specified locales.

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

    Parameters

    • pathsManager: any

      An instance of HTTPManager or FilesManager that will be used to load the provided paths. 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.

    • 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.

    • bundles: object[]

      A structure containing a list with the association between paths and their respective bundles. Each path is a relative or absolute string that defines a location where resourcebundles reside and must contain wildcards to define how locales and bundles are structured:

           - $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.
    • Default value finishedCallback: function | 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: function | 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

    see

    this.locales()

    Returns ReadonlyArray<string>

loadBundles

  • loadBundles(path: string, bundles: string[], finishedCallback?: function | null, progressCallback?: function | null): void
  • Adds extra bundles to the currently loaded translation data

    This method can only be called after the class has been initialized in case we need to add more bundles to the loaded translations.

    see

    this.initialize()

    Parameters

    • path: string

      The path where the extra bundles to load are located. See initialize method for information about the path format.

    • bundles: string[]

      List of bundles to load from the specified path

    • Default value finishedCallback: function | 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: function | 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?: function | null, progressCallback?: function | null): void
  • Adds extra languages to the list of currently loaded translation data.

    This method can only be called after the class has been initialized in case we need to add more translations.

    Parameters

    • locales: string[]

      List of languages for which we want to load the translations. The list will be appended to any previously loaded locales and included in the preferred translation order.

    • Default value finishedCallback: function | 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: function | 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): object
  • 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 object

    • [key: string]: string

Protected parseProperties

  • parseProperties(propertiesString: string): object
  • 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 object

    • [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.

    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 not 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.

    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

Generated using TypeDoc