@uxland/localization

UXL Localization

Build Status	Statements	Branches	Functions	Lines

Installation

npm i @uxland/localization

Usage

A default mixin is provided in order to be able to use localization functionalities and subscribe to language and locales changes.

export class Klass implements locale(BaseKlass) {}

In order to use custom formats in localization, define a new mixin provinding a factory including the desired formats.

const customLocale = localeMixin(() =>
  localizerFactory('en', {}, { number: { EUR: { style: 'currency', currency: 'EUR' } } })
);

export class Klass implements customLocale(BaseKlass) {}

Update current language

Set the current language that will be used in order to retrieve proper localization. Each time locales are updated, the event LANGUAGE_UPDATED will be published in order to inform all subscribers that the language has changed

setLanguage('en');

To retrieve current language from anywhere in the code, use:

getLanguage();

It is possible to reset locales to its default. This action will publish a LANGUAGE_RESET event.

resetLanguage();

By default, language is set to english en.

Update current formatters

Set the current formatters that will be used in order to retrieve proper localization. Each time locales are updated, the event FORMATTERS_UPDATED will be published in order to inform all subscribers that the formatters has changed.

Formatters must follow

setFormatters({ number: { EUR: { style: 'currency', currency: 'EUR' } } });

To retrieve current formatters from anywhere in the code, use:

getFormatters();

It is possible to reset locales to its default. This action will publish a FORMATTERS_RESET event.

resetFormatters();

Set locales dictionary

Locales must follow the next format:

const locales = [language]: {
		foo: {
			title: 'Title',
			subtitle: 'Subtitle'
		}
	};

Each time locales are updated, the event LOCALES_UPDATED will be published in order to inform all subscribers that the locales dictionary has changed.

setLocales(locales);

To retrieve current locales dictionary, use:

getLocales();

It is possible to reset locales to its default dictionary. This action will publish a LOCALES_RESET event.

resetLocales();

Localize

When localizing, the current language is used to retrieve language's locales. Providing a path to the localize function, this will return the corresponding string defined in locales dictonary.

const locales = [language]: {
		foo: {
			title: 'Title',
			subtitle: 'Subtitle',
			greetings: 'Hi!'
		}
	};
setLocales(locales);
localize(`foo.title`); // => "Title"

Arguments can also be provided to localize in order to get dynamic locales as it is specified bellow:

const locales = [language]: {
		foo: {
			title: 'Title',
			subtitle: 'Subtitle',
			greetings: 'Hi {name}!'
		}
setLocales(locales);
localize(`foo.greetings`, 'id', 'John Doe'); // => "Hello John Doe"
localize(`foo.greetings`, {id: 'John Doe'}); // => "Hello John Doe"

It is also possible to use pluralization as follows:

const locales = [language]: {
		foo: {
			title: 'Title',
			subtitle: 'Subtitle',
			greetings: 'Hi {name}!',
			cats: '{cats, plural, =0 {No cats} =1 {A cat} other {# cats}}'
		}
setLocales(locales);
localize(`foo.cats`, 'cats', 0); // => "No cats"
localize(`foo.cats`, 'cats', 1); // => "A cat"
localize(`foo.cats`, 'cats', 3); // => "3 cats"

Also currency can be localized as follows:

const locales = [language]: {
		foo: {
			title: 'Title',
			subtitle: 'Subtitle',
			greetings: 'Hi {name}!',
			cats: '{cats, plural, =0 {No cats} =1 {A cat} other {# cats}}',
			salary: 'Your salary is {salary, number, EUR}'
		}
setLocales(locales);
setFormatters({
        number: { EUR: { style: 'currency', currency: 'EUR' } },
      });
localize(`foo.salary`, { salary: 2000 }); // => "Your salary is €2,000.00"