VF i18n

Internationalization utilities used in VoxFeed.

Install

yarn add vf-i18n

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

VoxFeed/vf-i18n

VF i18n

Install

Usage

API

.get(locale, key, data)

.getDate(locale, date, format, timezone)

.getTime(locale, date, format, timezone)

.getDateTime(locale, date, format, timezone)

.getDuration(locale, duration)

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

.getTimeInterval(locale, date, fromDate)

.getNumber(locale, amount, decimals)

.getMoney(locale, amount, currency)

License