Nitroglycerin Pickle Machine

    vf-i18n

    1.1.5 • Public • Published

    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

    Install

    npm i vf-i18n

    DownloadsWeekly Downloads

    5

    Version

    1.1.5

    License

    MIT

    Unpacked Size

    73.3 kB

    Total Files

    37

    Last publish

    Collaborators

    • voxfeed