Package and application level translations made easy.
LANG- The locale to explicitly use for translation loading.
Translating messages is based around the concept of a "translator", which is an implementation around i18next that provides file system based resources bundles, in-memory caching, sane default configuration, automatic locale detection, plus all the features found in i18next.
The translator is designed for Node.js, primarily for package level translations, command line scripts, developer tools, and even applications, but not for the web or the browser.
To begin, instantiate a translator with
createTranslator with a list of namespaces
to load, a list of resource paths to locate bundles in, and an optional
options object. This returns a function that can be used for loading and retrieving
The first namespace provided becomes the "default namespace".
The returned translator function, aptly named
msg above, should be used anywhere that a message
string should be translated. It accepts translation key(s) as the 1st argument, an
optional object for interpolation as the 2nd argument, and an optional
options object as the 3rd argument.
Once the translator has been created, associated resource files must also be created.
The following options can be passed to
createTranslator. They cannot be customized after
boolean) - Automatically detect the locale from the environment. Defaults to
boolean) - Enable i18next debugging by logging info to the console. Defaults to
Locale | Locale) - Fallback locale(s) to use when the detected locale isn't translated. Defaults to
Locale) - Locale to explicitly use.
'all' | 'currentOnly' | 'languageOnly') - Order in which to load and lookup locale translations. Based on the i18next
'js' | 'json' | 'yaml') - File format resource bundles are written in. Defaults to
And these options can be passed to the created translator function (
string) - Default value to return if a translation was not found.
number) - Count used to determine plurals. More information.
string) - Context used for special parsing (male, female, etc). More information.
i18next.InterpolationOptions) - Interpolation options to pass down to i18next. More information.
Locale) - Force translation to this locale.
string | string) - Post-processors to run on the translation.
To load resource bundles, we require a locale. A locale is code based representation of a human
language and is based on IETF language tags.
Boost locales align with ISO 639, with the language being lowercased (
en), and the optional region
being uppercased and separated by a dash (
The locale is automatically detected from the environment using the following lookup strategies, one by one, until a valid locale is found.
- Defined by the
localeoption or through the translator's
- Passed on the command line with the
- Defined a
- Inherited from the operating system.
An example file structure of a resources folder, with multiple locale bundles, would look something like the following.
When retrieving messages with the translator function, the namespace can be targeted by prefixing the key and separating with a colon.
A translation is a message string (also known as copy) identified by a unique key (per namespace).
They can be retrieved using the translator function (
Translations inherit all functionality from i18next, so I suggest reading up on the essentials.
Contextual messages allow for different
messages based on contextual data, through the combination of multiple keys and the
Pluralizing messages is easily solved
through the combination of multiple keys and the
There are 2 forms of nesting. The first is nested keys within a namespace file, and they can be accessed using dot notation.
The second form is nested messages through a