Configuration

An example configuration object looks like that:

{
  translationPath: '/assets/i18n/{ language }/{ section }.json',
  translationFormat: 'JSON',
  loaderType: 'json',
  sections: [ ... ],
  defaultLanguage: 'en',
  allowedLanguages: [ 'en', 'it', 'hu' ],
  disableWarnings: true,
  currencyDefaultOptions: { USD: 'currencyDisplay = code' }
}

A typical configuration looks like that:

{
  translationPath: '/assets/i18n/{ language }/{ section }.json',
  sections: [
    'file1', 'file2', 'file3', ...
    { group: 'feature1', items: [ 'f1-file1', 'f1-file2', 'f1-file3', ... ] },
    ...
  ],
  defaultLanguage: 'en'
}

The configuration object has the following properties:

translationPath: string

The property defines the URL where NgTranslation will download the translation files from. The property value is a template string that has to contain 2 named parameters surrounded by curly brackets:

language: The code of the current or the requested language, e.g. 'en', 'en-GB', 'en-US', 'es', 'fr' etc.
section: The name of a partial translation file without the file extension, see the following property.

In the case of the above example the following files will be downloaded:

/assets
       /i18n
            /en
               /app.json
               /common.json
            /en-GB
                  /app.json
                  /common.json
            /hu
               /app.json
               /common.json

When you use this template:

translationPath: '/translations/{ section }.{ language }.json'

Then the following translation files will be downloaded:

/translations
             /app.en.json
             /app.en-GB.json
             /app.hu.json
             /common.en.json
             /common.en-GB.json
             /common.hu.json

All the other translation files will bo downloaded when they are needed, i.e. the user changes language or request a lazy loaded module.

translationFormat: string

Usually the translation texts are stored in JSON files, and the default value of translationFormat is 'JSON'. This parameter has role only when the texts are stored in different format, e.g. po, xliff, resx etc., and a converter is used to transform the translations into JSON format. Defining this parameter sets the default format for all sections.

loaderType: LoaderType

It defines the type of the loader used to download the translation files. The possible values are 'json', 'text', 'blob' and 'arraybuffer', the default value is 'json', This parameter is also used for custom converters.

sections: Array<string | Section | SectionGroup>

All translations can be stored in a big file, however, it is easier to maintain them when they are divided into several smaller files. The basis of the distribution can be - for example - that each Angular module has its own translation file. Even a bigger module can have more translation files. Another possibility is to collect the texts used application wide into one or more shared file. Or you can use your own strategy.

The sections property enlists the translation files, or sections in other word. A section actually is the name of a translation file without the file extension. The translation service cand download the necessary translation files for a lazy loaded module in lazy way as well, The download is initiated by the LoadTranslationsGuard that must be provided in the route definition of the lazy loaded module.

See more information about section configuration on the next pages.

defaultLanguage: string

The code of the default language. The translations of the eager loaded modules in the default language are downloaded at the start of the application.

allowedLanguages: Array<string>

An optional list of language codes. If the list is not supplied, the service tries to download thr translation resources for any requested language. WHen the list is supplied and it does not contain the specified language, the service omits the request. If the language code has a country/region part (e.g. en-UK) and the list contains the neutral language (i.e. en), then the neutral language will be used.

disableWarnings: boolean

An optional value to disable NgTranslation warning messages.The default value is false.

currencyDefaultOptions: object

An optional object to add default style options for currencies. The property names of the object are the currency codes, and the values are strings containing the options set by default. The options are defined in the same way as currency formatting in localization. The following example corrects the incorrect number of fractional digits at the Hungarian currency:

{
  ...
  currencyDefaultOptions: { HUF: 'minfd = 0; maxfd = 0' }
}

See the possible options in the Localiyation chapter.

Documentation