ostrio:i18n

v3.2.0Published 4 months ago

support support

Reactive i18n and l10n isomorphic driver

Object based, fast, lightweight (334 lines with comments) and reactive internationalization isomorphic driver for Meteor with support of placeholders, and user's locale auto-detection.

Not tied to Blaze, can be used with Vue.js, React.js or any other JS solution.

Install:

meteor add ostrio:i18n

Import:

1import I18N from 'meteor/ostrio:i18n';

Object-based structure

1/* Isomorphic (Both Server and Client) */
2const i18nConfig = {
3  settings: { //--> Config object
4    defaultLocale: "en",
5    ru: {
6      code: "ru",
7      isoCode: "ru-RU",
8      name: "Русский"
9    },
10    en: {
11      code: "en",
12      isoCode: "en-US",
13      name: "English"
14    }
15  },
16  ru:{ //--> Localization with key of country two-letter code
17    property: "value",
18    property2: {
19      nestedProp: "value"
20    },
21    dynamicProperty(){
22      return `<a href="/${this.currentLocale.get()}/info">info</a>`;
23    }
24  },
25  en:{ //--> Localization with key of country two-letter code
26    property: "value",
27    property2: {
28      nestedProp: "value"
29    },
30    dynamicProperty(){
31      return `<a href="/${this.currentLocale.get()}/info">info</a>`;
32    }
33  }
34  ...
35};
36
37import I18N from 'meteor/ostrio:i18n';
38const i18n = new I18N({i18n: i18nConfig});

Initialization

1import I18N from 'meteor/ostrio:i18n';
2const i18n = new I18N(config);
  • config.i18n {Object} - Internalization object
  • config.returnKey {Boolean} - Return key if l10n value not found, default: true
  • config.helperName {String} - Template helper name, default: i18n
  • config.helperSettingsName {String} - Settings helper name, default: i18nSettings

API

get([locale,] key, [replacements...])

  • locale {String} - [Optional] Two-letter locale string, used to force locale, if not set current locale is used
  • key {String} - l10n key like: object.path.to.key
  • replacements.. {String|[String]|Object} - [Optional] Replacements for placeholders in l10n string
1i18n.get('object.path.to.key'); // Current locale, no replacements
2
3i18n.get(locale, param); // Force locale, no replacements
4i18n.get('en', 'object.path.to.key');
5
6i18n.get(param, replacements); // Current locale, with replacements
7i18n.get('object.path.to.key', 'Michael'); // Hello {{username}} -> Hello Michael
8
9i18n.get(locale, param, replacements); // Force locale, with replacements
10i18n.get('en', 'object.path.to.key', 'John Doe'); // Hello {{username}} -> Hello John Doe

has([locale,] key)

Determine whenever key is exists in configuration file(s).

  • locale {String} - [Optional] Two-letter locale string, used to force locale, if not set current locale is used
  • key {String} - l10n key like: object.path.to.key
1i18n.has('object.path.to.key'); // Current locale
2i18n.has(locale, param); // Force locale
3i18n.has('ca', 'object.path.to.key'); //false
4i18n.has('en', 'object.path.to.key'); //true

setLocale(locale)

  • locale {String} - Two-letter locale code
1i18n.setLocale(locale);

addl10n(l10n)

  • l10n {Object} - Object with language set
1i18n.addl10n({
2  en: { // <- Object's root is the language two-letter code
3    newKey: "New Value"
4  }
5});

Get current localization at any environment

1i18n.currentLocale.get(); // Reactive on Client

Get current default locale

1i18n.defaultLocale;

Get configuration object

1i18n.langugeSet();
2/* Returns:
3{
4  current: 'en', // Current locale
5  locales: ['ru', en], // List of locales
6  // All locales
7  all: [{
8    code: "ru",
9    isoCode: "ru-RU",
10    name: "Русский",
11    path: "i18n/ru/"
12  },{
13    code: "en",
14    isoCode: "en-US",
15    name: "English",
16    path: "i18n/en/"
17  }],
18  // All locales except current
19  other: [{
20    code: "ru",
21    isoCode: "ru-RU",
22    name: "Русский",
23    path: "i18n/ru/"
24  }],
25}
26*/

Get specific key from configuration object

  • key {String} - One of the keys: current, all, other, locales, currentISO, currentName, currentPath
1i18n.getSetting('current'); // en

Blaze specific usage

Usage in Blaze templating

Client's browser locale

1i18n.userLocale; // en-US

Template helpers

Template helpers requires templating package to be installed. i18n helper - accepts locale, key and replacements

<p>{{i18n 'sample.hello'}}</p>
<p>{{{i18n 'sample.html'}}}</p>
<p>{{i18n 'sample.fullName'}}</p>
<p>{{i18n 'sample.fullName' 'Michael' 'A.' 'Macht'}}</p>
<p>{{i18n 'en' 'sample.fullName' 'Michael' 'A.' 'Macht'}}</p>
<p>{{i18n 'de' 'sample.fullName' first='Michael' middle='A.' last='Macht'}}</p>
<p>{{i18n 'sample.fullName' first='Michael' middle='A.' last='Macht'}}</p>
<p>{{i18n 'sample.fullName' first='Michael' middle='A.' third='Macht'}}</p>

Change name of the helper via config object: config.helperName

i18nSettings - accepts configuration object key, one of current, all, other, locales

{{#each i18nSettings 'all'}}
  ...
{{/each}}

Change name of the helper via config object: config.helperSettingsName

Template language switcher example

<template name="langSwitch">
  {{#each i18nSettings 'all'}}
    {{#if compare code '==' currentLocale}}
      <span title="Current language">{{name}}</span>&nbsp;
    {{else}}
      <a href="#" data-switch-language="{{code}}">{{name}}</a>&nbsp;
    {{/if}}
  {{/each}}
</template>
1Template.langSwitch.helpers({
2  currentLocale(){
3    return i18n.currentLocale.get()
4  }
5});
6
7Template.langSwitch.events({
8  'click [data-switch-language]'(e) {
9    e.preventDefault();
10    i18n.setLocale(e.currentTarget.dataset.switchLanguage);
11    return false;
12  }
13});

Template helpers compare, ==, Session and many more comes from: ostrio:templatehelpers package.

Support this project: