i18njs

!logo
-----

> Simplistic I18N tool for universal/isomorphic Javascript.


----

Usage with RequireJS

To use with RequireJS I'd advise to also use the plugin
requirejs-i18njs to be able to precompile the templates
that are in your translation files for your production code.

----

Usage with Handlebars

You can register your helper simply by using the .get() function of i18njs

``javascript
Handlebars.registerHelper('i18n',
function () {
// Pass all arguments except the last one
// that is a Handlebars specific.
return i18njs.get.apply(i18njs,
Array.prototype.slice.call(arguments, 0, -1));
}
);
`

then in your templates :

`javascript
// Arguments after the 'key' are optionals
{{i18n 'key' data options lang}}
`

----

Installation

Either

`node
npm install --save i18njs
`

or

`node
bower install --save i18njs
`
----

Usage

Import it the way you want into your project :

`javascript
// CommonJS
var i18njs = require('i18njs');
`

`javascript
// AMD
define(['i18njs'], function (i18njs) {
// use i18njs
});
`

`html
// Global


`

$3

Your localized strings are simple json objects.

Namespaces can be as deep as you need.

`javascript

var en_locales = {
'hello_world': {
'hello': 'Hello',
'world': 'World'
}
};

var fr_locales = {
'hello_world': {
'hello': 'Bonjour',
'world': 'Monde'
}
};

// i18n.add(language, [namespace,] locales);
i18n.add('en', 'first_level_namespace', en_locales);
i18n.add('fr', 'first_level_namespace', fr_locales);

`

$3

By default, language is set to en.

`javascript

i18n.setLang('fr');

`

$3

`javascript

i18n.getCurrentLang();

`

$3

`javascript

i18n.getDico();

`

$3

If needed, you can also check for the presence of a specific localized string in a particular language.

You can check only the language too.

`javascript
// i18n.has([key,] lang)
i18n.has('first_level_namespace.hello_world.hello', 'en');
// true

i18n.has('first_level_namespace.hello_world.hello');
// true

i18n.has('en');
// true

i18n.has('de');
// false

i18n.has('hello_world.bye', 'en');
// false

i18n.has('test');
// false
`

$3

`javascript

i18n.listLangs();
// ['en', 'fr']

`

$3

`javascript

// i18n.get(key[, data, options][, lang]);
i18n.get('first_level_namespace.hello_world.hello');
// Hello

i18n.get('first_level_namespace.hello_world.hello', 'fr');
// Bonjour

`

$3

It uses a basic templating engine, the same as underscore.

It works in the form of {{=interpolate}}, {{evaluate}} or {{-escape}} :

`javascript
// localized strings
var en_locales = {
'st': '{{=interpolate}}{{for(var i = 0, max = 5; i < max; i += 1) {}} to{{}}} {{-escape}}'
};

// context used in the templated string
var data = {
'interpolate': 'Hello',
'escape': '\'\' & "World"'
};

// register the localized string
i18n.add('en', en_locales);

// give it a context with the data object
var st = i18n.get('st', data);
// "Hello to to to to to '<the>' `&` "World""

`

$3

You can also change delimiters by passing the third options arguments

`javascript

var st = i18n.get('st', data, {
evaluate: /<%([\s\S]+?)%>/g;
interpolate: /<%=([\s\S]+?)%>/g;
escape: /<%-([\s\S]+?)%>/g;
});

`

Will result in these delimiters <%=interpolate%>, <%evaluate%> or <%-escape%>

$3

If you need to have a special key always replaced by the same value (a brand for example),
you can set it as a default.

This key will be then replaced across your application's localized strings and you
won't need to pass it as a context object to your .get().

`javascript
var fr = {
welcome: 'Bienvenue sur {{=brand}}'
};

var en = {
welcome: 'Welcome to {{=brand}}'
};

var defaults = {
fr: {
brand: 'Ma Marque'
},
en: {
brand: 'My Brand'
}
};

i18n.add('fr', fr);
i18n.add('en', en);
i18n.setDefaults(defaults);

i18n.get('welcome');
//Welcome to My Brand
i18n.get('brand');
// My Brand
`

You don't have to use localized defaults if you don't need to :

`javascript
var defaults = {
brand: 'My Brand'
};

i18n.setDefaults(defaults);
i18n.setLang('fr');

i18n.get('welcome');
//Bienvenue sur My Brand
`

You can also check your defaults :

`javascript
i18n.getDefaults();
//{
// brand: 'My Brand',
// fr: {
// brand: 'Ma Marque'
// },
// en: {
// brand: 'My Brand'
// }
//}
``