@k14v/i18njs
v0.3.1
Published
Library to internationalize literals
Downloads
28
Readme
I18njs
i18njs it's made to intended simplify and normalize internationalization and make compatible with all kind of javascript environments.
Motivation
In general, many logics that has an exposed API to end users should have the accessibility to handle literals that the user can understand in their language. Many libraries try to solve this by using static translation catalogs, but typically when the catalog is heavily loaded with data, the scalability is actually seen to be well below performance. To handle this with a dynamic way, the store has the capability to load fragments of catalogs using remotes sources of data using a sourcemap to track the needed snippets, this becomes a logic asynchronous with smaller pieces of load that also can handle changes without impacting performance.
Using this system the library includes a feedback system to manage the current state and decide if its logic needs to be frozen to wait until the process is finished. This library offers many ways to manage it (subscriptions, events or promises).
Getting started
$ npm install --save @k14v/i18njs
i18n
Provides a instance of i18njs to handle multiple locales asynchronously
Parameters
options
options
Examples
const i18n = i18njs({
locale: 'es',
locales: ['de', 'es', 'en'],
resolver: (locale) => ({ foo: 'bar' }),
});
Returns object i18n instance
options
Option struct.
Type: object
Properties
locale
string? predefined default locale, if setted it will execute setLocale internally to load the locale resource, keep it undefined to handle this behaviour outside the logic.locales
(Array<string> | object)? Array of strings of available locales using the standard ISO_639-1resolver
function used to resolve asyncronous locale resources
i18n.trls
Translation singleton with all interpolation utilities corresponding to the current locale
Type: object
i18n.setLocale
Updates the current locale and refresh trls singleton
Parameters
locale
string [description]
Returns promise
i18n.getLocales
Obtain and array of string in ISO_639 format with all loaded locales
Returns Array Array of string ISO_639-1
i18n.getLocale
Obtain current locale ISO_639
i18n.getCatalog
Get current catalog of literal translations from cache
Returns object
i18n.getCatalogs
Get all catalogs of literal translations
Returns object
i18n.subscribe
Subcribe to the changes of loading state flow
Examples
const unsubscribe = i18n.subscribe(({ type, locale }) => {
switch(type) {
case 'loading':
// dispatch function to handle loading state
break;
case 'loaded':
// dispatch function to handle loading state
break;
case 'error':
// dispatch function to handle error state
break;
}
});
Returns object
i18njs.fetch
Fetch i18n instance with preloaded locale resource
Examples
i18njs
.fetch({
locale: 'es',
resolver: () => Promise.resolve({ 'foo': 'bar' })
...options
})
.then((i18n) => {
i18n.trls.__('foo') // bar
});
Using translators
trls.__('esto es una prueba')
Dynamic translations
const i18n = i18njs({
locales: {
en: {
'Group': 'Grupo',
'The cow': 'La vaca',
'the fence': 'la valla',
'The rabbit': 'El conejo',
'the table': 'la mesa',
'Sometimes I drink %d beers': {
one: 'A veces me bebo una cerveza',
other: 'A veces me bebo muchas cervezas',
},
'%s jumped over %s, %d times': {
one: '%s saltó por encima de %s, una vez',
other: '%s saltó por encima de %s, %d veces'
}
}
},
});
i18n.trls.__('Sometimes I drink 1 beers')
// A veces me bebo una cerveza
i18n.trls.__('Sometimes I drink 10 beers')
// A veces me bebo muchas cervezas
i18n.trls.__('The cow jumped over the fence, 10 times')
// La vaca saltó por encima de la valla, 10 veces
i18n.trls.__('The rabbit jumped over the table, 1 times')
// El conejo saltó por encima de la mesa, una vez
Integrations
- react https://github.com/k14v/react-i18njs
Peding changes
- Implement source map