vf-i18n v1.1.5

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:

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.

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.

Formats:

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.

Formats:

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.

Formats:

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.

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.

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.

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.

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.

Examples:

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

License

MIT