Skip to content
/ i18njs Public

Library to internationalize literals compatible with browser and nodejs

License

Notifications You must be signed in to change notification settings

k14v/i18njs

Repository files navigation

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

src/i18n.js:21-133

Provides a instance of i18njs to handle multiple locales asynchronously

Parameters

Examples

const i18n = i18njs({
 locale: 'es',
 locales: ['de', 'es', 'en'],
 resolver: (locale) => ({ foo: 'bar' }),
});

Returns object i18n instance

options

src/i18n.js:29-29

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-1
  • resolver function used to resolve asyncronous locale resources

i18n.translate

src/i18n.js:53-53

Translation function

Type: object

i18n.setLocale

src/i18n.js:60-71

Updates the current locale and refresh translate

Parameters

Returns promise

i18n.getLocales

src/i18n.js:77-79

Obtain and array of string in ISO_639 format with all loaded locales

Returns Array Array of string ISO_639-1

i18n.getLocale

src/i18n.js:85-87

Obtain current locale ISO_639

Returns string ISO_639-1

i18n.getCatalog

src/i18n.js:93-95

Get current catalog of literal translations from cache

Returns object

i18n.getCatalogs

src/i18n.js:101-103

Get all catalogs of literal translations

Returns object

i18n.subscribe

src/i18n.js:124-124

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

src/i18n.js:150-150

Fetch i18n instance with preloaded locale resource

Examples

i18njs
  .fetch({
    locale: 'es',
    resolver: () => Promise.resolve({ 'foo': 'bar' })
    ...options
   })
  .then((i18n) => {
    i18n.translate('foo') // bar
  });

Using translators

translate('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.translate('Sometimes I drink 1 beers')
// A veces me bebo una cerveza
i18n.translate('Sometimes I drink 10 beers')
// A veces me bebo muchas cervezas
i18n.translate('The cow jumped over the fence, 10 times')
// La vaca saltó por encima de la valla, 10 veces
i18n.translate('The rabbit jumped over the table, 1 times')
// El conejo saltó por encima de la mesa, una vez

Integrations

Peding changes

  • Implement source map