❤
npm
Sign UpSign In

i18njs

2.1.7 • Public • Published

logo

Simplistic I18N tool for universal/isomorphic Javascript.

npm version bower version travis

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 () {
        // 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 :

// 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 &#x27;&lt;the&gt;&#x27; &#x60;&amp;&#x60; &quot;World&quot;"
 

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
i18n.get('brand');
// My Brand

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

var defaults = {
    brand: 'My Brand'
};
 
i18n.setDefaults(defaults);
i18n.setLang('fr');
 
i18n.get('welcome');
//Bienvenue sur My Brand

You can also check your defaults :

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

Readme

Keywords

Package Sidebar

Install

npm i i18njs

Repository

github.com/yoannmoinet/i18njs

Homepage

github.com/yoannmoinet/i18njs

Weekly Downloads

60

Version

2.1.7

License

MIT

Last publish

Collaborators

  • yoannmoinet
Try on RunKit
Report malware