@telefonica/i18n

I18N

This package provides a way of translating tokens based on a locale key. The mechanism is simple, you only need to provide an object with translations and a key to be applied. Tokens are allowed to have variables, which will be interpolated later. I.E.:

'%(hello_message)Hola, %(user_name)1$s, bienvenido a %(app_name)2$s'
    ^                       ^       ^                            ^
    1                       2       3                            4

In the above example, number 1 is the token's comment. Number 2 is a variable comment. Number 3 and 4 are variables, that will be replaced with the values passed to the translation funcion as we will explain in the sections below.

API

getI18n

getI18n(
  locale: string,
  translations: {[token: string]: {[localeKey: string]: string}}
): {
    translate: (token: string, ...variables: string | number[]) => string,
    translatePlural: (tokenSingular: string, tokenPlural: string, count: number, ...variables: string | number[]) => string
}

This is the default export, and has to be called to get the I18N object that will provide the functions declared below that will be used to translate tokens. translations keys are the tokens, and values are objects with the shape localeKey -> translationString. I.E.:

I18N.init('es-ES', {
  '%(account_management_page_title)Gestionar usuarios': {
    'es-ES': 'Gestionar usuarios',
    'en-GB': 'Manage users',
  },
  '%(account_management_button_primary)Aceptar': {
    'es-ES': 'Aceptar',
    'en-GB': 'OK',
  },
});

I18N.translate

I18N.translate(
    token: string,
    ...variables: Array<string | number>
): string

This is the main translation function. It receives a token to translate and an arbitrary number of variables to be interpolated. I.E.:

const userName = 'Manolo';

I18N.translate('%(hello_message)Hola, %(user_name)1$s, bienvenido a %(app_name)2$s', userName, 'RapidGator');

Here, translate function will first replace the token given the localeKey and translationsMap passed in upon initialization. Then it will replace the first token's variable for the value of userName, and the same for the second variable. An example return value could be:

Hello, Manolo, welcome to RapidGator

I18N.translatePlural

I18N.translatePlural(
    tokenSingular: string,
    tokenPlural: string,
    count: number,
    ...variables: Array<string | number>
): string

This functions helps translate texts when the token has a different values for its singular and plural variations. Its behaviour is simple, if count equals 1 it will call, I18N.translate passing in the tokenSingular, otherwise it will pass in the tokenPlural.

Local Development

Below is a list of commands you will probably find useful.

yarn start

Runs the project in development/watch mode. Your project will be rebuilt upon changes.

yarn build

Bundles the package to the dist folder. The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module).

yarn test

Runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit.