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

Handlebars.registerHelper( ' i18n ' , function () { return i18njs.get. apply (i18njs, arguments); } );

then in your templates :

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

Installation

Either

npm install -- save i18njs

or

bower install -- save i18njs

Usage

Import it the way you want into your project :

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

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

// Global < script type = " text/javascript " src = " ./dist/i18njs.min.js " ></ script > < script type = " text/javascript " > // use i18njs </ script >

Add locales

Your localized strings are simple json objects.

Namespaces can be as deep as you need.

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);

Change language

By default, language is set to en .

i18n.setLang( ' fr ' );

Get current language

i18n.getCurrentLang();

Get dictionary

i18n.getDico();

Check for availability

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.

// 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

List available languages

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

Get basic localized string

// 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

Get templated string

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

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

// 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 ' : ' \' <the> \' `&` "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""

Change delimiters

You can also change delimiters by passing the third options arguments

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%>

Add default values for templates

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() .

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

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