lightweight simple translation module with dynamic json storage
npm install i18n-2 * Designed to work out-of-the-box with Express.js
* Lightweight simple translation module with dynamic json storage.
* Uses common __('...') syntax in app and templates.
* Stores language files in json files compatible to webtranslateit json format.
* Adds new strings on-the-fly when first used in your app.
* No extra parsing needed.
Run the following:
``
npm install i18n-2Simple Example
Note: If you plan on using the module with Express.js, please view Using with Express.js, below.
`javascript
// Load Module and Instantiate
var i18n = new (require('i18n-2'))({
// setup some locales - other locales default to the first locale
locales: ['en', 'de']
});
// Use it however you wish
console.log( i18n.__("Hello!") );
`API:
The i18n function is the return result from calling require('i18n-2'). You use this to instantiate an I18n instance and set any configuration options. You'll probably only do this if you're not using the expressBind method.
You'll use this method to attach the i18n functionality to the request object inside Express.js. The app argument should be your Express.js app and the options argument should be the same as if you were calling new i18n(options). See "Using with Express.js" at the end of this README for more details.
Translates a string according to the current locale. Also supports sprintf syntax, allowing you to replace text, using the node-sprintf module.
For example:
`javascript`
var greeting = i18n.__('Hello %s, how are you today?', 'Marcus');
this puts Hello Marcus, how are you today?. You might also add endless arguments or even nest it.javascript`
var greeting = i18n.__('Hello %s, how are you today? How was your %s?',
'Marcus', i18n.__('weekend'));
which puts Hello Marcus, how are you today? How was your weekend?
You might even use dynamic variables. They get added to the current locale file if they do not yet exist.
`javascript`
var greetings = ['Hi', 'Hello', 'Howdy'];
for (var i = 0; i < greetings.length; i++) {
console.log( i18n.__(greetings[i]) );
};
which outputs:
Hi
Hello
Howdy
You can also use nested object :
`json`
{
"foo": {
"bar": "ok"
}
}
And use dot notation to access the value :javascript`
i18n.__('foo.bar');$3
Different plural forms are supported as a response to count:`javascript`
var singular = i18n.__n('%s cat', '%s cats', 1);
var plural = i18n.__n('%s cat', '%s cats', 3);
this gives you 1 cat and 3 cats. As with these could be nested:`javascript`
var singular = i18n.__n('There is one monkey in the %%s', 'There are %d monkeys in the %%s', 1, 'tree');
var plural = i18n.__n('There is one monkey in the %%s', 'There are %d monkeys in the %%s', 3, 'tree');
putting There is one monkey in the tree or There are 3 monkeys in the tree.
You may also use in your locale object/file :
`json`
{
"catEat": {
"one": "%d cat eat the %s",
"other": "%d cat eat the %s"
}
}
and use as you would use __() (directly, or from locale) :`javascript`
var singular = i18n.__n('catEat', 1, 'mouse');
var plural = i18n.__n('catEat', 10, 'mouse');$3
Returns a string containing the current locale. If no locale has been specified then it default to the value specified in defaultLocale.
Sets a locale to the specified string. If the locale is unknown, the locale defaults to the one specified by defaultLocale. For example if you have locales of 'en' and 'de', and a defaultLocale of 'en', then call .setLocale('ja') it will be equivalent to calling .setLocale('en').
To be used with Express.js or another framework that provides a request object. Generally you would want to use this by setting the query option to true.
This method takes in an Express.js request object, looks at the query property, and specifically at the lang parameter. Reading the value of that parameter will then set the locale.
For example:
`
example.com/?lang=de
Will then do:javascript`
setLocale('de')$3
To be used with Express.js or another framework that provides a request object. Generally you would want to use this by setting the session option to true.
This methods takes in an Express.js request object, looks at the variable locale (you may override this behaviour by changing the option sessionVarName, which defaults to locale) contained in the session object, and it will set the locale to that value.
For example, if the session is :
{ user: { ... }, locale: 'de' }
Then setLocaleFromSessionVar will do setLocale('de')
To be used with Express.js or another framework that provides a request object. Generally you would want to use this by setting the subdomain option to true.
This method takes in an Express.js request object, looks at the hostname, and extracts the sub-domain. Reading the value of the subdomain the locale is then set.
For example:
`
de.example.com
Will then do:javascript`
setLocale('de')$3
To be used with Express.js or another framework that provides a request object. This method takes a request object, looks at it's cookies property and tries to find a cookie named cookieName (default: lang).
See Using with Express.js for a complete example.
For example:
`javascript`
console.log(req.cookies.lang) //=> 'de'
setLocaleFromCookie()
Will then do:javascript`
setLocale('de')$3
To be used with some desktop application environment (like Electron or NW.js) or console. This method tries to get language code from LANG environment variable. For example, it get de from de_DE.UTF-8.
For example:
`javascript`
console.log(process.env.LANG) //=> 'en_US.UTF-8'
setLocaleFromEnvironmentVariable()
Will then do:javascript`
setLocale('en')$3
To be used with Express.js or another framework that provides a request object. This method works if a request option has been specified when the i18n object was instantiated.
This method returns true if the locale specified by getLocale matches a language desired by the browser's Accept-language header.
When you instantiate a new i18n object there are a few options that you can pass in. The only required option is locales.
You can pass in the locales in two ways: As an array of strings or as an object of objects. For example:
`javascript`
locales: ['en', 'de']
This will set two locales (en and de) and read in the JSON contents of both translation files. (By default this is equal to "./locales/NAME.js", you can configure this by changing the and extension options.) Additionally when you pass in an array of locales the first locale is automatically set as the defaultLocale.
You can also pass in an object, like so:
`
locales: {
"en": {
"Hello": "Hello"
},
"de": {
"Hello": "Hallo"
}
}
In this particular case no files will ever be read when doing a translation. This is ideal if you are loading your translations from a different source. Note that no is set when you pass in an object, you'll need to set it yourself.
You can explicitly define a default locale to be used in cases where .setLocale(locale) is used with an unknown locale. For example if you have locales of 'en' and 'de', and a defaultLocale of 'en', then call .setLocale('ja') it will be equivalent to calling .setLocale('en').
These default to "./locales" and ".js" accordingly. They are used for saving and reading the locale data files (see the locales option for more information on how this works).
When your server is in production mode it will read these files only once and then cache the result. It will not write any updated strings when in production mode.
When in development, or testing, mode the files will be read on every instantiation of the i18n object. Additionally newly-detected strings will be automatically added, and written out, to the locale JSON files.
A generated en.js inside ./locales/ may look something like:`json`
{
"Hello": "Hello",
"Hello %s, how are you today?": "Hello %s, how are you today?",
"weekend": "weekend",
"Hello %s, how are you today? How was your %s.": "Hello %s, how are you today? How was your %s.",
"Hi": "Hi",
"Howdy": "Howdy",
"%s cat": {
"one": "%s cat",
"other": "%s cats"
},
"There is one monkey in the %%s": {
"one": "There is one monkey in the %%s",
"other": "There are %d monkeys in the %%s"
},
"tree": "tree"
}
that file can be edited or just uploaded to webtranslateit for any kind of collaborative translation workflow.
You can specify a function that will be used to extract base file name for each locale. It may be used for instance to keep in the locales only region-specific translations and move all what's shared to the base files.
It will take effect only when locales are provided as an array and base is a function that returns a string value. You can skip this mechanism for particular locale if base returns no value.
Each locale is merged with its base (if found) such that locale translations override the base. If the base file does not exist or is not parsable - it will not be created.
Following example takes de.js and en.js as bases respectively for each locale:`javascript`
locales: ['at-de', 'de-de', 'at-en', 'de-en'],
base: function(locale) {
return locale.slice(-2);
}$3
Optional custom methods to override JSON.parse() and JSON.stringify(), respectively. One possible use for this is to allow for file formats other than JSON. For example:`javascript`
var i18n = new (require('i18n-2'))({
locales: ['en', 'de'],
extension: '.yaml',
parse: function (data) {
return require('js-yaml').safeLoad(data);
},
dump: function (data) {
return require('js-yaml').safeDump(data);
}
});$3
These options are to be used with Express.js or another framework that provides a request object. In order to use the subdomain and query options you must specify the request option, passing in the Express.js request object.
If you pass in a request object a new i18n property will be attached to it, containing the i18n instance.
Note that you probably won't need to use request directly, if you use expressBind it is taken care of automatically.
Setting the subdomain option to true will run the setLocaleFromSubdomain method automatically on every request.
Setting the session option to true will run the setLocaleFromSessionVar method automatically on every request.
By default the query option is set to true. Setting the query option to false will stop the setLocaleFromQuery method from running automatically on every request.
Copy the __, __n, getLocale, and isPreferredLocale methods over to the object specified by the register property.`javascript`
var obj = {};
new i18n({ 'register': obj })
console.log( obj.__("Hello.") );$3
By default the devMode property is automatically set to be false if Node.js is in production mode and true otherwise. You can override this by setting a different value to the devMode option.
Sets the indent string for JSON.stringify when updating the locale files. Defaults to a tab character. Might be useful when you use a source formatter in your project.
In your app.js:
`javascript
// load modules
var express = require('express'),
i18n = require('i18n-2');
// Attach the i18n property to the express request object
// And attach helper methods for use in templates
i18n.expressBind(app, {
// setup some locales - other locales default to en silently
locales: ['en', 'de'],
// change the cookie name from 'lang' to 'locale'
cookieName: 'locale'
});
// This is how you'd set a locale from req.cookies.
// Don't forget to set the cookie either on the client or in your Express app.
app.use(function(req, res, next) {
req.i18n.setLocaleFromCookie();
next();
});
// Set up the rest of the Express middleware
app.use(app.router);
app.use(express.static(__dirname + '/public'));
`$3
javascript`
module.exports = {
index: function(req, res) {
res.render("index", {
title: req.i18n.__("My Site Title"),
desc: req.i18n.__("My Site Description")
});
}
};$3
(This example uses the Swig templating system.)
`
{% extends "page.swig" %}
{% block content %}
{{ desc }}
Debugging
uses the debug module to output debug messages to the console. To output all debug messages, set the DEBUG environment variable:`
DEBUG=i18n-2:*
This will output debugging messages from the module.Changelog
* 0.6.0: added setLocaleFromEnvironmentVariable()
* 0.5.0: base files for locales
* 0.4.7: configurable indent for locale json files
* 0.4.6: bug fixes, new feature (dot notation &