@cherrypulp/i18n
v1.4.7
Published
Simple I18n wrapper around a global object
Downloads
111
Readme
I18n
Simple I18n wrapper around a global object.
Installation
npm install @cherrypulp/i18n
Quick start
Initialization
import I18n from '@cherrypulp/i18n';
const options = {
globalName: 'translations', // name of the autoloaded global variable
forceDisplayKeys: true, // display the key if the label is not found (else it return an empty string)
storeNotFounds: true, // store every key that are not found in a variable called "_notFounds" inside the global
};
const translations = {
foo: 'Bar',
hello: 'Hello :name',
user: {
firstname: 'First name',
},
};
const i18n = new I18n(translations, 'en', options);
// 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
You can now use
__
as an alias ofget
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"
i18n.__('foo', null, 'fr'); // return "foo" (alias)
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"
VueJS
import { VueI18n } from '@cherrypulp/i18n';
const settings = {
translations: {
foo: 'BAR',
},
language: 'en',
options: {
forceDisplayKeys: false,
},
};
Vue.use(VueI18n, settings);
// 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>
Composition
import { createApp } from 'vue';
import { createI18n, useI18n, __, choice } from '@cherrypulp/i18n';
const app = createApp();
const options = {
translations: {
foo: 'BAR',
},
language: 'en',
};
// retrieve a global instance or create one (this instance is a singleton)
const i18n = useI18n(options.translations, options.language);
// create a new instance
const i18nOtherInstance = createI18n(options.translations, options.language);
app.config.globalProperties.__ = __;
// then
i18n.get('foo'); // return "BAR"
i18n.__('foo'); // return "BAR" (alias)
__('foo'); // return "BAR" (shortcut using global instance)
// 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.