VF i18n

Internationalization utilities used in VoxFeed.

Install

yarn add vf-i18n

or

npm install --save vf-i18n

Usage

Require the module in your project and instantiate a i18n class.

const VFi18n = require('vf-i18n');
const i18n = new VFi18n();

Optionally you can pass the following parameters to the constructor:

Parameter	Type	Description
strings	Object	An object containing all the translations available, grouped by each supported locale.
onMissingString	Function	A function that is called everytime a requested translation is not available in strings for a given locale. An object with locale and key is passed on each call.
fallbackLocales	Array[String]	If a translation is not available in a specific locale, then if fallbackLocales are specified the library will try to find a translation in one of those locales (from first to last). First translation available is returned.

Example:

const VFi18n = require('vf-i18n');

const strings = {
  en: {
    GREETING: 'Hello {name}!',
    THANKS: 'Thank you',
    BYE: 'Good bye!'
  },
  es: {
    GREETING: '¡Hola {name}!',
    THANKS: 'Gracias'
  },
  de: {
    GREETING: 'Hallo {name}!',
    THANKS: 'Danke'
  },
  it: {
    GREETING: 'Ciao {name}!',
    THANKS: 'Grazie'
  }
};

const fallbackLocales = ['en']; // If not found in specified locale, will fallback to English.

const onMissingString = ({locale, key}) => {
  console.log(`String not found for locale "${locale}" and key "${key}"`);
};

const i18n = new VFi18n({
  strings,
  fallbackLocales,
  onMissingString
});

i18n.get('es', 'THANKS'); // Gracias

i18n.get('it', 'BYE'); // Will return "Good bye!" (fallback).

i18n.get('de', 'MISSING_KEY'); // Will call onMissingString({locale: 'de', key: 'MISSING_KEY'}) and return "" (default string).

API

Once instantiated, the library exposes the following API:

.get(locale, key, data)

Returns a translation string for a given locale and key combination. It uses messageformat internally, so every formatting option supported by messageformat (plurals, categories, variables...) is also supported by this function.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
key	String	Required. The key identifying the string to be translated.
data	Object	Options and variables to be passed to the formatter.

Examples:

i18n.get('it', 'THANKS'); // Grazie
i18n.get('es', 'GREETING', {name: 'Morty'}); // ¡Hola Morty!

.getDate(locale, date, format, timezone)

Returns a localized date string. It uses Moment Localized formats internally, so available formats are mapped to one Moment format.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
date	Date	Required. The date to be formatted.
format	String	Required. The style used to format the date string. Available formats are: short, medium, long and full.
timezone	String	Time zone name, used to convert the date prior to formatting. Defaults to UTC.

Formats:

Format	Moment Format	Example
short	L	10/14/2017
medium	ll	Oct 14, 2017
long	LL	October 14, 2017
full	LLLL	Saturday, October 14, 2017

Examples:

const date = new Date(2017, 9, 14);

i18n.getDate('en', date, 'short'); // 10/14/2017
i18n.getDate('en', date, 'long', 'America/Los_Angeles'); // October 14, 2017

.getTime(locale, date, format, timezone)

Returns a localized time string. It uses Moment Localized formats internally, so available formats are mapped to one Moment format.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
date	Date	Required. The date to be formatted (only time is used).
format	String	Required. The style used to format the time. Available formats are: short, medium, long and full.
timezone	String	Time zone name, used to convert the time prior to formatting. Defaults to UTC.

Formats:

Format	Moment Format	Example
short	LT	6:30 PM
medium	LTS	6:30:05 PM
long	LTS	6:30:05 PM
full	LTS z	6:30:05 PM CDT

Examples:

const date = new Date('2017-10-14T18:30:05.000Z');

i18n.getTime('en', date, 'short'); // 6:30:05 PM
i18n.getTime('en', date, 'long', 'Asia/Tokyo'); // 3:30:05 AM JST

.getDateTime(locale, date, format, timezone)

Returns a localized date-time string. It uses Moment Localized formats internally, so available formats are mapped to one Moment format.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
date	Date	Required. The date-time to be formatted.
format	String	Required. The style used to format the date-time. Available formats are: short, medium, long and full.
timezone	String	Time zone name, used to convert the date-time prior to formatting. Defaults to UTC.

Formats:

Format	Moment Format	Example
short	L LT	10/14/2017 6:30 PM
medium	lll	Oct 14, 2017 6:30 PM
long	LLL	October 14, 2017 6:30 PM
full	LLLL	Sunday, October 15, 2017 3:30 AM

Examples:

const date = new Date('2017-10-14T18:30:05.000Z');

i18n.getDateTime('en', date, 'short'); // 10/14/2017 6:30 PM
i18n.getDateTime('en', date, 'long', 'Asia/Tokyo'); // October 14, 2017 6:30 PM

.getDuration(locale, duration)

For a given time duration in milliseconds, returns a human-readable localized string. It uses Moment Duration Humanize internally.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
duration	Integer	Required. Time duration in milliseconds.

Examples:

const ONE_HOUR = 60 * 60 * 1000;

i18n.getDuration('en', 5 * ONE_HOUR); // 5 hours
i18n.getDuration('en', 24 * ONE_HOUR); // a day

.getRelativeTime(locale, date, style, units, fromDate)

For a given date, returns the distance in time from now (or other specific date) as a human-readable localized string. It uses Yahoo's Intl RelativeFormat internally.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
date	Date	Required. The first date to calculate the distance in time.
style	String	Formatting style. Available styles are: best fit and numeric (see more). Defaults to best fit.
units	String	Whether to force the string to use a specific time unit. Available units are: second, second-short, minute, minute-short, hour, hour-short, day, day-short, month, month-short, year and year-short (see more).
fromDate	Date	The second date to calculate the distance in time. Defaults to new Date().

Examples:

const ONE_DAY = 24 * 60 * 60 * 1000;
const date1 = new Date(Date.now() + ONE_DAY);
const date2 = new Date(Date.now() + 7 * ONE_DAY);

i18n.getRelativeTime('en', date1); // tomorrow
i18n.getRelativeTime('en', date1, 'numeric'); // in 1 day
i18n.getRelativeTime('en', date1, 'numeric', date2); // 6 days ago

.getTimeInterval(locale, date, fromDate)

Returns a human-readable localized string for the duration between 2 dates. It uses .getDuration internally.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
date	Date	Required. The first date to calculate the duration.
fromDate	Date	The second date to calculate the duration. Defaults to new Date().

Examples:

const ONE_DAY = 24 * 60 * 60 * 1000;
const date1 = new Date(Date.now() + ONE_DAY); // Date in future
const date2 = new Date(Date.now() - ONE_DAY); // Date in past

i18n.getTimeInterval('en', date1); // a day
i18n.getTimeInterval('en', date2); // a day
i18n.getTimeInterval('en', date1, date2); // 2 days

.getNumber(locale, amount, decimals)

It returns a formatted number string. It uses Intl.NumberFormat internally.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
amount	Number	Required. Number to be formatted.
decimals	Integer	Number of decimals. Defaults to 0.

Examples:

i18n.getNumber('en', 1234.56); // 1,235
i18n.getNumber('en', 1, 5); // 1.00000

.getMoney(locale, amount, currency)

It returns a formatted currency string, always rounded to 2 decimals. It uses Intl.NumberFormat internally.

Parameter	Type	Description
locale	String	Required. The locale in which the translation is required.
amount	Number	Required. Money amount to be formatted.
currency	String	Required. Currency ISO code (Ej. USD, EUR). It is used to print the currency and choose its symbol ($, €...).

Examples:

i18n.getMoney('en', 10, 'MXN'); // $10.00 MXN
i18n.getMoney('en', 1200.059999, 'USD'); // $1,200.06 USD

License

MIT