README

I18n

Simple I18n wrapper around a global object.

Installation

npm install @cherrypulp/i18n

Quick start

Initialization

import I18n from '@cherrypulp/i18n';

const translations = {
    foo: 'Bar',
    hello: 'Hello :name',
    user: {
        firstname: 'First name',
    },
};
const i18n = new I18n(translations, 'en');

// or

window.translations = {
    foo: 'bar',
    hello: 'Hello :Name',
    user: {
        firstname: 'John Doe',
    },
};
const i18n = new I18n();

window.translations is loaded by default, translations will be merged with it.

Methods

`set`

Set translations for the given language (default language is the current one).

i18n.set({
    bar: 'BAZ',
}, 'en');

`add`

Add translations to the given language (default language is the current one).

i18n.add({
    foo: 'BAR',
}, 'en');

`setLocale`

Set current locale.

i18n.setLocale('fr'); // i18n.locale return 'fr'

`has`

Return true if the given key exist in translations.

i18n.has('foo'); // return true
i18n.has('bat'); // return false

`get`

Return the translation for the given key. You can pass an object as 2nd arguments to replace placeholders in the translation.

i18n.get('foo'); // return "bar"
i18n.get('user.firstname'); // return "John Doe"
i18n.get('bat'); // return "bat"
i18n.get('foo', null, 'fr'); // return "foo"

All placeholders are prefixed with a :.

i18n.get('hello', {name: 'world'}); // return "Hello World"

If your placeholder contains all capital letters, or only has its first letter capitalized, the translated value will be capitalized accordingly:

// @example {hello: 'Hello :NAME'}
i18n.get('hello', {name: 'john'}); // return "Hello JOHN"

// @example {hello: 'Hello :Name'}
i18n.get('hello', {name: 'john'}); // return "Hello John"

`fetch`

Retrieve a translation from the locale.

i18n.fetch('en.foo'); // return "bar"

`choice`

Singular and plural forms are separated by a | (= pipe).

// @example {apples: 'There is one apple|There are many apples'}
i18n.choice('apples', 4); // return "There are many apples"

You may even create more complex pluralization rules which specify translation strings for multiple number ranges:

// @example {apples: '{0} There are none|[1,19] There are some|[20,*] There are many'}
i18n.choice('apples', 4); // return "There are some"

ReactJS

import { useI18n } from '@cherrypulp/i18n';

const MyComponent = () => {
    const options = {
        translations: {
            foo: 'BAR',
        },
        language: 'en',
    };
    
    const i18n = useI18n(options); // retrieve your instance via `useI18n()`
    
    // you can work with multiple instance if you like :-) (options will beignored if the instance already exists)
    const i18nOtherInstance = useI18n(options, 'your-namespace'); // retrieve your instance via `useI18n(null, 'your-namespace')`
};

// then

i18n.get('foo'); // return "BAR"

// or in templates

<div>{i18n.get('foo')}</div>

VueJS

import { VueI18n } from '@cherrypulp/i18n';

const options = {
    translations: {
        foo: 'BAR',
    },
    language: 'en',
};

Vue.use(VueI18n, options);

// then

this.$i18n.get('foo'); // return "BAR"
Vue.$i18n.get('foo'); // return "BAR"
this.__('foo'); // return "BAR"

// or in templates

<div>{{ $i18n.get('foo') }}</div>
<div>{{ __('foo') }}</div>

Versioning

Versioned using SemVer.

Contribution

Please raise an issue if you find any. Pull requests are welcome!

Author

Stéphan Zych - monkeymonk

License

This project is licensed under the MIT License - see the LICENSE file for details.

Usage no npm install needed!