i18n-for-browser

Modern translation module for web.

Install

npm i i18n-for-browser
# or
yarn add i18n-for-browser

CDN

i18n-for-browser is also available on unpkg.com as UMD, which exposes global object i18n.

<script src="https://unpkg.com/i18n-for-browser?main=umd"></script>

API

Module exposes next API:

export default globalConfig;
export {
    I18nConfigInstance,
    I18nPluralLocale,
    I18nLocale,
    I18nLangLocales,
    I18nLocales,
    I18nFallbacks,
    I18nUnknownPhraseListener,
    I18nProcessor,
    I18nConfig,
    I18nForkConfig,
    I18nParams,
    I18nPluralParams,
    pluralIntervalProcessor,
    mustacheProcessor,
    __,
    __mf,
    __n,
    __m
};

Description of this methods you can find in Documentation.

Shirt description:

i18n

Global config. Instanse of Config.

Usage example

import i18n, {
    pluralIntervalProcessor,
    __,
    __n
} from 'i18n-for-browser';

/**
 * Set global config.
 */
i18n.configure({
    /**
     * Store of translations.
     */
    locales: {
        'en': {
            /**
             * Simple translation example.
             */
            'cat': 'cat',
            /**
             * Plutal translation example.
             */
            '%s cats': {
                'one': '%s cat',
                'other': '%s cats'
            },
            /* ... */
        },
        'ru': {
            /**
             * Пример простого перевода.
             */
            'cat': 'кошка',
            /**
             * Пример перевода множественного числа.
             */
            '%s cats': {
                'one': '%s кошка',
                'few': '%s кошки',
                'many': '%s кошек',
                'other': '%s кошка'
            },
            /* ... */
        }
    },
    /**
     * Cookie name to store locale.
     */
    cookieName: 'yourcookiename'
});

console.log(__('cat')); // Uses global config.

/**
 * Create config fork with some overrides. 
 */
const i18nFork = i18n.fork({
    /**
     * List of post processors.
     */
    processors: [pluralIntervalProcessor]
});
/**
 * Bind new config to method.
 */
const __pi = i18nFork.bind(__n);

/**
 * Now you able to use plural intervals.
 */
console.log(
    __pi('[0] no dog|[2,5] some dogs|[6,11] many dogs|[12,36] dozens of dogs|a horde of %s dogs|[100,] too many dogs', 3) // Uses bound config.
);

__()

Translates a single phrase and adds it to locales if unknown.

Usage example

/**
 * Basic usage 
 */
__('cat')
/**
 * As template string
 */
__`cat`
/**
 * Supports sprintf formatting
 */
__('%d cats', 3)
/**
 * Sprintf formatting with template string
 */
__`${3} cats`
/**
 * Sprintf formatting with few arguments
 */
__('%d cats with %s', 3, 'long tails')
/**
 * Mustache templates are supported with `mustacheProcessor`
 */
__('Hello {{name}}', { name: 'Marcus' })
/**
 * First argument as object with specified locale
 */
__({ phrase: 'Hello', locale: 'ru' })

__mf()

Supports the advanced MessageFormat as provided by excellent messageformat module. You should definetly head over to messageformat.github.io for a guide to MessageFormat. i18n-for-browser takes care of new MessageFormat('en').compile(msg); with the current msg loaded from it's json files and cache that complied fn in memory. So in short you might use it similar to __() plus extra object to accomblish MessageFormat's formating.

Usage example

/**
 * Basic usage, also works as raw `__` method
 */
__mf('cat')
/**
 * Basic replacement
 */
__mf('Hello {name}', { name: 'Marcus' })
/**
 * Also work with sprintf formatting
 */
__mf('Hello {name}, how was your %s?', 'test', { name: 'Marcus' })

__n()

Plurals translation of a single phrase. Singular and plural forms will get added to locales if unknown. Returns translated parsed and substituted string based on count parameter.

Usage example

/**
 * Basic usage
 */
__('%s cats', 2)
/**
 * As template string
 */
__`${3} cats`
/**
 * Can work without translation in config
 */
__('%d dog', '%d dogs', 3)
/**
 * First argument as object with specified locale
 */
__n({ singular: '%s cat', plural: '%s cats', locale: 'nl', count: 3 })

__m()

Returns a map of translations for a given phrase in each language.

Usage example

/**
 * Basic usage
 */
__m(__, 'Hello')

Express middleware helper

To provide translations to client from your express app you can use this helper.

import i18nExpressHelper from 'i18n-for-browser/lib/middleware';
// or 
const i18nExpressHelper = require('i18n-for-browser/lib/middleware');
// ...
// Before this `i18n` should already initialized.
app.use(i18nExpressHelper(i18nNodeConfig));
// ...

<!DOCTYPE html>
<html>
    <head>
        <title>views/layout.ejs</title>
        <%- initI18nForBrowser() %>
        <script src="js-file-with-imported-i18n-for-browser.js"></script>
    </head>
    <body>
        <%- body %>
    </body>
</html>