i18n

Lightweight simple translation module with dynamic JSON storage. Supports plain vanilla Node.js apps and should work with any framework (like Express, restify and probably more) that exposes an app.use() method passing in res and req objects. 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.

Install

1npm install i18n --save

Synopsis

1const http = require('http')
2const path = require('path')
3const { I18n } = require('i18n')
4
5const i18n = new I18n({
6  locales: ['en', 'de'],
7  directory: path.join(__dirname, 'locales')
8})
9
10const app = http.createServer((req, res) => {
11  i18n.init(req, res)
12  res.end(res.__('Hello'))
13})
14
15app.listen(3000, '127.0.0.1')

This wires up a plain http server and return "Hello" or "Hallo" depending on browsers 'Accept-Language'. The first configured locale 'en' will default in case the browser doesn't include any of those locales in his request.

---

Usage

With 0.12.0 i18n now provides options to be used as instance or singleton.

• Instances allow to work with multiple different configurations and encapsulate resources and states.
• Singletons allow to share configuration, state and resources across multiple requires, modules or files.

Before 0.12.0 singleton usage was the only option. Instances give much more intuitive control and should be considered the "better practice" in complex setups.

As Instance

Minimal example, just setup two locales and a project specific directory.

1/**
2 * require I18n with capital I as constructor
3 */
4const { I18n } = require('i18n')
5
6/**
7 * create a new instance with it's configuration
8 */
9const i18n = new I18n({
10  locales: ['en', 'de'],
11  directory: path.join(__dirname, 'locales')
12})

Alternatively split creation and configuration, useful when split up into different modules for bootstrapping.

1/**
2 * require I18n with capital I as constructor
3 */
4const { I18n } = require('i18n')
5
6/**
7 * create a new instance
8 */
9const i18n = new I18n()
10
11/**
12 * later in code configure
13 */
14i18n.configure({
15  locales: ['en', 'de'],
16  directory: path.join(__dirname, '/locales')
17})

As Singleton

Same Minimal example, just setup two locales and a project specific directory.

1const i18n = require('i18n')
2
3/**
4 * configure shared state
5 */
6i18n.configure({
7  locales: ['en', 'de'],
8  directory: path.join(__dirname, '/locales')
9})

Now you are ready to use a global i18n.__('Hello').

Require i18nin another file reuses same configuration and shares state:

1const i18n = require('i18n')
2
3module.exports = () => {
4  console.log(i18n.__('Hello'))
5}

CLI within global scope

In your cli, when not registered to a specific object:

1var greeting = i18n.__('Hello')

Global assumes you share a common state of localization in any time and any part of your app. This is usually fine in cli-style scripts. When serving responses to http requests you'll need to make sure that scope is NOT shared globally but attached to your request object.

Middleware in express.js

In an express app, you might use i18n.init to gather language settings of your visitors and also bind your helpers to response object honoring request objects locale, ie:

1// Configuration
2app.configure(function () {
3  // [...]
4
5  // default: using 'accept-language' header to guess language settings
6  app.use(i18n.init)
7
8  // [...]
9})

in your apps methods:

1app.get('/de', function (req, res) {
2  var greeting = res.__('Hello')
3})

in your templates (depending on your template engine)

1<%= __('Hello') %>
2
3${__('Hello')}

Some examples for common setups

See tested examples inside /examples for some inspiration in node and express or browse these gists:

PLEASE NOTE: Those gist examples worked until node 0.12.x only

• plain Node.js + HTTP
• plain Node.js + restify
• Express 3 + cookie
• Express 3 + hbs 2 (+ cookie)
• Express 3 + Mustache (+ cookie)
• Express 4 + cookie

For serving the same static files with different language url, you could:

1app.use(express.static(__dirname + '/www'))
2app.use('/en', express.static(__dirname + '/www'))
3app.use('/de', express.static(__dirname + '/www'))

---

API

The api is subject of incremental development. That means, it should not change nor remove any aspect of the current api but new features and options will get added that don't break compatibility backwards within a major version.

i18n.configure()

You should configure your application once to bootstrap all aspects of i18n. You should not configure i18n in each loop when used in an http based scenario. During configuration, i18n reads all known locales into memory and prepares to keep that superfast object in sync with your files in filesystem as configured

1i18n.configure({
2  locales: ['en', 'de'],
3  directory: path.join(__dirname, 'locales')
4})

Since 0.7.0 you may even omit the locales setting and just configure a directory. i18n will read all files within that directory and detect all given locales by their filenames.

1i18n.configure({
2  directory: path.join(__dirname, 'locales')
3});

list of all configuration options

1i18n.configure({
2  // setup some locales - other locales default to en silently
3  locales: ['en', 'de'],
4
5  // fallback from Dutch to German and from any localized German (de-at, de-li etc.) to German
6  fallbacks: { nl: 'de', 'de-*': 'de' },
7
8  // you may alter a site wide default locale
9  defaultLocale: 'en',
10
11  // will return translation from defaultLocale in case current locale doesn't provide it
12  retryInDefaultLocale: false,
13
14  // sets a custom cookie name to parse locale settings from - defaults to NULL
15  cookie: 'yourcookiename',
16
17  // sets a custom header name to read the language preference from - accept-language header by default
18  header: 'accept-language',
19
20  // query parameter to switch locale (ie. /home?lang=ch) - defaults to NULL
21  queryParameter: 'lang',
22
23  // where to store json files - defaults to './locales' relative to modules directory
24  directory: './mylocales',
25
26  // control mode on directory creation - defaults to NULL which defaults to umask of process user. Setting has no effect on win.
27  directoryPermissions: '755',
28
29  // watch for changes in JSON files to reload locale on updates - defaults to false
30  autoReload: true,
31
32  // whether to write new locale information to disk - defaults to true
33  updateFiles: false,
34
35  // sync locale information across all files - defaults to false
36  syncFiles: false,
37
38  // what to use as the indentation unit - defaults to "\t"
39  indent: '\t',
40
41  // setting extension of json files - defaults to '.json' (you might want to set this to '.js' according to webtranslateit)
42  extension: '.json',
43
44  // setting prefix of json files name - default to none '' (in case you use different locale files naming scheme (webapp-en.json), rather then just en.json)
45  prefix: 'webapp-',
46
47  // enable object notation
48  objectNotation: false,
49
50  // setting of log level DEBUG - default to require('debug')('i18n:debug')
51  logDebugFn: function (msg) {
52    console.log('debug', msg)
53  },
54
55  // setting of log level WARN - default to require('debug')('i18n:warn')
56  logWarnFn: function (msg) {
57    console.log('warn', msg)
58  },
59
60  // setting of log level ERROR - default to require('debug')('i18n:error')
61  logErrorFn: function (msg) {
62    console.log('error', msg)
63  },
64
65  // used to alter the behaviour of missing keys
66  missingKeyFn: function (locale, value) {
67    return value
68  },
69
70  // object or [obj1, obj2] to bind the i18n api and current locale to - defaults to null
71  register: global,
72
73  // hash to specify different aliases for i18n's internal methods to apply on the request/response objects (method -> alias).
74  // note that this will *not* overwrite existing properties with the same name
75  api: {
76    __: 't', // now req.__ becomes req.t
77    __n: 'tn' // and req.__n can be called as req.tn
78  },
79
80  // When set to true, downcase locale when passed on queryParam; e.g. lang=en-US becomes en-us.
81  // When set to false, the queryParam value will be used as passed;
82  // e.g. lang=en-US remains en-US.
83  preserveLegacyCase: true, // defaults to true
84
85  // set the language catalog statically
86  // also overrides locales
87  staticCatalog: {
88    de: {
89      /* require('de.json') */
90    }
91  },
92
93  // use mustache with customTags (https://www.npmjs.com/package/mustache#custom-delimiters) or disable mustache entirely
94  mustacheConfig: {
95    tags: ['{{', '}}'],
96    disable: false
97  },
98
99  // Parser can be any object that responds to .parse & .stringify
100  parser: JSON
101})

The locale itself is gathered directly from the browser by header, cookie or query parameter depending on your setup.

In case of cookie you will also need to enable cookies for your application. For express this done by adding app.use(express.cookieParser())). Now use the same cookie name when setting it in the user preferred language, like here:

1res.cookie('yourcookiename', 'de', { maxAge: 900000, httpOnly: true })

After this and until the cookie expires, i18n.init() will get the value of the cookie to set that language instead of default for every page.

Some words on register option

Used especially in a CLI-like script. You won't use any i18n.init() to guess language settings from your user, thus i18n won't bind itself to any res or req object and will work like a static module.

1var anyObject = {}
2
3i18n.configure({
4  locales: ['en', 'de'],
5  register: anyObject
6})
7
8anyObject.setLocale('de')
9anyObject.__('Hallo') // --> Hallo

Cli usage is a special use case, as we won't need to maintain any transaction / concurrency aware setting of locale, so you could even choose to bind i18n to global scope of node:

1i18n.configure({
2  locales: ['en', 'de'],
3  register: global
4})
5
6i18n.setLocale('de')
7__('Hello') // --> Hallo

Some words on staticCatalog option

Instead of letting i18n load translations from a given directory you may pass translations as static js object right on configuration. This supports any method that returns a key:value translation object ({ Hello: 'Hallo', Cat: 'Katze' }). So you might even mix native json with js modules and parsed yaml files, like so:

1// DEMO: quickly add yaml support
2const yaml = require('js-yaml')
3const fs = require('fs')
4
5// configure and load translations from different locations
6i18n.configure({
7  staticCatalog: {
8    de: require('../../locales/de-as-json.json'),
9    en: require('../../locales/en-as-module.js'),
10    fr: yaml.safeLoad(fs.readFileSync('../../locales/fr-as-yaml.yml', 'utf8'))
11  },
12  defaultLocale: 'de'
13})

NOTE: Enabling staticCatalog disables all other fs realated options such as updateFiles, autoReload and syncFiles

Some words on parser option

Instead of parsing all file contents as JSON, you can parse them as YAML or any other format you like

1const YAML = require('yaml')
2
3i18n.configure({
4  extension: '.yml',
5  parser: YAML
6})

i18n.init()

When used as middleware in frameworks like express to setup the current environment for each loop. In contrast to configure the i18n.init() should be called within each request-response-cycle.

1var app = express()
2app.use(cookieParser())
3app.use(i18n.init)

When i18n is used like this, the i18n.init() tries to

1. guess the language of a visitor by it's browser settings, cookie or query parameter
2. set that language in any of the "usual" objects provided by the framework

Express would call i18n.init(req, res, next), which is "classic" and adopted by many frameworks. Thus i18n will attach it's api to that schema:

1{
2  req: {
3    locals: {},
4    res: {
5      locals: {},
6    }
7  }
8}

and add it's extra attributes and methods, like so:

1{
2  req: {
3    locals: {
4      locale: "de",
5      __: [function],
6      __n: [function],
7      [...]
8    },
9    res: {
10      locals: {
11        locale: "de",
12        __: [function],
13        __n: [function],
14        [...]
15      },
16      locale: "de",
17      __: [function],
18      __n: [function],
19      [...]
20    },
21    locale: "de",
22    __: [function],
23    __n: [function],
24    [...]
25  }
26}

Now each local object (ie. res.locals) is setup with it's own "private" locale and methods to get the appropriate translation from the global catalog.

i18n.__()

Translates a single phrase and adds it to locales if unknown. Returns translated parsed and substituted string.

1// template and global (this.locale == 'de')
2__('Hello') // Hallo
3__('Hello %s', 'Marcus') // Hallo Marcus
4__('Hello {{name}}', { name: 'Marcus' }) // Hallo Marcus
5
6// scoped via req object (req.locale == 'de')
7req.__('Hello') // Hallo
8req.__('Hello %s', 'Marcus') // Hallo Marcus
9req.__('Hello {{name}}', { name: 'Marcus' }) // Hallo Marcus
10
11// scoped via res object (res.locale == 'de')
12res.__('Hello') // Hallo
13res.__('Hello %s', 'Marcus') // Hallo Marcus
14res.__('Hello {{name}}', { name: 'Marcus' }) // Hallo Marcus
15
16// passing specific locale
17__({ phrase: 'Hello', locale: 'fr' }) // Salut
18__({ phrase: 'Hello %s', locale: 'fr' }, 'Marcus') // Salut Marcus
19__({ phrase: 'Hello {{name}}', locale: 'fr' }, { name: 'Marcus' }) // Salut Marcus

i18n.__n()

Plurals translation of a single phrase. Singular and plural forms will get added to locales if unknown. Returns translated parsed and substituted string based on last count parameter.

1// short syntax is best suited for reading
2// --> writes '%s cat' to both `one` and `other` plurals
3__n('%s cat', 1) // --> 1 Katze
4__n('%s cat', 3) // --> 3 Katzen
5
6// long syntax works fine in combination with `updateFiles`
7// --> writes '%s cat' to `one` and '%s cats' to `other` plurals
8// "one" (singular) & "other" (plural) just covers the basic Germanic Rule#1 correctly.
9__n('%s cat', '%s cats', 1) // 1 Katze
10__n('%s cat', '%s cats', 3) // 3 Katzen
11
12// scoped via req object (req.locale == 'de')
13req.__n('%s cat', 1) // 1 Katze
14req.__n('%s cat', 3) // 3 Katzen
15
16// scoped via res object (res.locale == 'de')
17res.__n('%s cat', 1) // 1 Katze
18res.__n('%s cat', 3) // 3 Katzen
19
20// passing specific locale
21__n({ singular: '%s cat', plural: '%s cats', locale: 'fr' }, 1) // 1 chat
22__n({ singular: '%s cat', plural: '%s cats', locale: 'fr' }, 3) // 3 chats
23
24// the all in one object signature
25__n({ singular: '%s cat', plural: '%s cats', locale: 'fr', count: 1 }) // 1 chat
26__n({ singular: '%s cat', plural: '%s cats', locale: 'fr', count: 3 }) // 3 chats

When used in short form like __n(phrase, count) the following will get added to your json files:

1__n('%s dog', 1)

1{
2  "%s dog": {
3    "one": "%s dog",
4    "other": "%s dog"
5  }
6}

When used in long form like __n(singular, plural, count) you benefit form passing defaults to both forms:

1__n('%s kitty', '%s kittens', 0)

1{
2  "%s kitty": {
3    "one": "%s kitty",
4    "other": "%s kittens"
5  }
6}

You might now add extra forms to certain json files to support the complete set of plural forms, like for example in russian:

1{
2  "%s cat": {
3    "one": "%d кошка",
4    "few": "%d кошки",
5    "many": "%d кошек",
6    "other": "%d кошка",
7  }
8}

and let __n() select the correct form for you:

1__n('%s cat', 0) // --> 0 кошек
2__n('%s cat', 1) // --> 1 кошка
3__n('%s cat', 2) // --> 2 кошки
4__n('%s cat', 5) // --> 5 кошек
5__n('%s cat', 6) // --> 6 кошек
6__n('%s cat', 21) // --> 21 кошка

Note i18n.__n() will add a blueprint ("one, other" or "one, few, other" for example) for each locale to your json on updateFiles in a future version.

i18n.__mf()

Supports the advanced MessageFormat as provided by excellent messageformat module. You should definetly head over to messageformat.github.io for a guide to MessageFormat. i18n takes care of new MessageFormat('en').compile(msg); with the current msg loaded from it's json files and cache that complied fn in memory. So in short you might use it similar to __() plus extra object to accomplish MessageFormat's formatting. Ok, some examples:

1// assume res is set to german
2res.setLocale('de')
3
4// start simple
5res.__mf('Hello') // --> Hallo
6
7// can replace too
8res.__mf('Hello {name}', { name: 'Marcus' }) // --> Hallo Marcus
9
10// and combines with sprintf
11res.__mf('Hello {name}, how was your %s?', 'test', { name: 'Marcus' }) // --> Hallo Marcus, wie war dein test?
12
13// now check out a plural rule
14res.__mf('{N, selectordinal, one{# cat} two{# cats} few{# cats} other{# cats}}', {
15  N: 1
16})
17
18// results for "1" in   (all use "one")
19// en --> 1 cat
20// de --> 1 Katze
21// fr --> 1 chat
22// ru --> 1 кошка       ru uses "__one__" when ending on "1"
23
24// results for "0" in   (most use "others")
25// en --> 0 cats
26// de --> 0 Katzen
27// fr --> 0 chat        fr uses "__one__" for zero
28// ru --> 0 кошек       ru uses "__many__"
29
30// results for "2" in   (most use "others")
31// en --> 2 cat
32// de --> 2 Katze
33// fr --> 2 chat
34// ru --> 2 кошки       ru uses "__few__" when ending on "1"
35
36// results for "5" in   (most use "others")
37// en --> 5 cat
38// de --> 5 Katze
39// fr --> 5 chat
40// ru --> 5 кошек       ru uses "__many__"
41
42// results for "21" in  (most use "others")
43// en --> 21 cat
44// de --> 21 Katze
45// fr --> 21 chat
46// ru --> 21 кошка       ru uses "__one__" when ending on "1"

Take a look at Mozilla to quickly get an idea of what pluralization has to deal with. With __mf() you get a very powerful tool, but you need to handle it correctly.

But MessageFormat can handle more! You get ability to process:

• Simple Variable Replacement (similar to mustache placeholders)
• SelectFormat (ie. switch msg based on gender)
• PluralFormat (see above and ranges)

Combinations of those give superpower, but should get tested well (contribute your use case, please!) on integration.

i18n.__l()

Returns a list of translations for a given phrase in each language.

1i18n.__l('Hello') // --> [ 'Hallo', 'Hello' ]

This will be usefull when setting up localized routes for example (kudos to @xpepermint, #150):

1// this will match routes
2// EN --> /:locale/products/:id?
3// ES --> /:locale/productos/:id?
4app.get(__l('/:locale/products/:id?'), function (req, res) {
5  // guess what you might use req.params.locale for?
6})

i18n.__ln() to get plurals will come up in another release...

i18n.__h()

Returns a hashed list of translations for a given phrase in each language.

1i18n.__h('Hello') // --> [ { de: 'Hallo' }, { en: 'Hello' } ]

i18n.__hn() to get plurals will come up in another release...

i18n.setLocale()

Setting the current locale (ie.: en) globally or in current scope.

1setLocale('de')
2setLocale(req, 'de')
3req.setLocale('de')

Use setLocale to change any initial locale that was set in i18n.init(). You get more control on how when and which objects get setup with a given locale. Locale values are inherited within the given schema like in i18n.init() Let's see some examples:

1i18n.setLocale(req, 'ar') // --> req: مرحبا res: مرحبا res.locals: مرحبا
2i18n.setLocale(res, 'ar') // --> req: Hallo res: مرحبا res.locals: مرحبا
3i18n.setLocale(res.locals, 'ar') // --> req: Hallo res: Hallo res.locals: مرحبا

You'll get even more control when passing an array of objects:

1i18n.setLocale([req, res.locals], req.params.lang) // --> req: مرحبا res: Hallo res.locals: مرحبا

or disable inheritance by passing true as third parameter:

1i18n.setLocale(res, 'ar', true) // --> req: Hallo res: مرحبا res.locals: Hallo

i18n.getLocale()

Getting the current locale (ie.: en) from current scope or globally.

1getLocale() // --> de
2getLocale(req) // --> de
3req.getLocale() // --> de

i18n.getLocales()

Returns a list with all configured locales.

1i18n.getLocales() // --> ['en', 'de', 'en-GB']

i18n.getCatalog()

Returns a whole catalog optionally based on current scope and locale.

1getCatalog() // returns catalog for all locales
2getCatalog('de') // returns just for 'de'
3
4getCatalog(req) // returns catalog for all locales
5getCatalog(req, 'de') // returns just for 'de'
6
7req.getCatalog() // returns catalog for all locales
8req.getCatalog('de') // returns just for 'de'

Attaching helpers for template engines

In general i18n has to be attached to the response object to let it's public api get accessible in your templates and methods. As of 0.4.0 i18n tries to do so internally via i18n.init, as if you were doing it in app.configure on your own:

1app.use(function (req, res, next) {
2  // express helper for natively supported engines
3  res.locals.__ = res.__ = function () {
4    return i18n.__.apply(req, arguments)
5  }
6
7  // [...]
8
9  next()
10})

Different engines need different implementations, so yours might miss or not work with the current default helpers. This one showing an example for mustache in express:

1// register helper as a locals function wrapped as mustache expects
2app.use(function (req, res, next) {
3  // mustache helper
4  res.locals.__ = function () {
5    return function (text, render) {
6      return i18n.__.apply(req, arguments)
7    }
8  }
9
10  // [...]
11
12  next()
13})

You could still setup your own implementation. Please refer to Examples below, post an issue or contribute your setup.

Output formats

As inspired by gettext there is currently support for sprintf-style expressions. You can also use mustache syntax for named parameters.

sprintf support

1var greeting = __('Hello %s, how are you today?', 'Marcus')

this puts Hello Marcus, how are you today?. You might add endless arguments and even nest it.

1var greeting = __('Hello %s, how are you today? How was your %s.', 'Marcus', __('weekend'))

which puts Hello Marcus, how are you today? How was your weekend.

You might need to have repeated references to the same argument, which can be done with sprintf.

1var example = __('%1$s, %1$s, %1$s', 'repeat')

which puts

repeat, repeat, repeat

In some cases the argument order will need to be switched for different locales. The arguments can be strings, floats, numbers, etc.

1var example = __('%2$d then %1$s then %3$.2f', 'First', 2, 333.333)

which puts

2 then First then 333.33

mustache support

You may also use mustache syntax for your message strings. To pass named parameters to your message, just provide an object as the last parameter. You can still pass unnamed parameters by adding additional arguments.

1var greeting = __('Hello {{name}}, how are you today?', { name: 'Marcus' })

this puts Hello Marcus, how are you today?. You might also combine it with sprintf arguments...

1var greeting = __('Hello {{name}}, how was your %s.', __('weekend'), { name: 'Marcus' })

and even nest it...

1var greeting = __( __('Hello {{name}}, how was your %s?', { name: 'Marcus' }), __('weekend') )

which both put Hello Marcus, how was your weekend.

how about markup?

Including markup in translation and/or variables is considered to be bad practice, as it leads to side effects (translators need to understand it, might break it, inject malformed markup or worse). But well, mustache supports unescaped markup out-of-the-box (Quote from https://mustache.github.io/mustache.5.html):

All variables are HTML escaped by default. If you want to return unescaped HTML, use the triple mustache: {{{name}}}.

So this will work

1var greeting = __('Hello {{{name}}}, how are you today?', { name: '<u>Marcus</u>' })

as expected:

1Hello <u>Marcus</u>, how are you today

basic plural support

two different plural forms are supported as response to count:

1var singular = __n('%s cat', '%s cats', 1)
2var plural = __n('%s cat', '%s cats', 3)

this puts 1 cat or 3 cats and again these could get nested:

1var singular = __n('There is one monkey in the %%s', 'There are %d monkeys in the %%s', 1, 'tree')
2var plural = __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. Passing all 3 parameters would write a one and other to your json. For reading you might just use 2 parameters, too:

1__n('%s cat', 1) // --> 1 Katze
2__n('%s cat', 3) // --> 3 Katzen

ranged interval support

use mathematical intervals to declare any own plural rules based on ISO 31-11 notation. Let's assume the following json snippet:

1"dogs": {
2    "one": "one dog",
3    "other": "[0] no dog|[2,5] some dogs|[6,11] many dogs|[12,36] dozens of dogs|a horde of %s dogs|[100,] too many dogs"
4}

this will result in

1__n('dogs', 0) // --> no dog
2__n('dogs', 1) // --> one dog
3__n('dogs', 2) // --> some dogs
4__n('dogs', 10) // --> many dogs
5__n('dogs', 25) // --> dozens of dogs
6__n('dogs', 42) // --> a horde of 42 dogs
7__n('dogs', 199) // --> too many dogs

The rules are parsed in sequenced order, so the first match will skip any extra rules. Example:

1{
2    "dogs":"[0]no dog|[1]one dog|[,10[ less than ten dogs|[,20[ less than 20 dogs|too many dogs"
3}

results in

1// interval matched by number
2__n('dogs', 0) // --> no dog
3__n('dogs', 1) // --> one dog
4__n('dogs', 2) // --> less than ten dogs
5__n('dogs', 9) // --> less than ten dogs
6__n('dogs', 10) // --> less than 20 dogs
7__n('dogs', 19) // --> less than 20 dogs
8__n('dogs', 20) // --> too many dogs
9__n('dogs', 199) // --> too many dogs
10
11// no interval returned, but found a catchall
12__('dogs') // --> too many dogs

See en.json example inside /locales for some inspiration on use cases. Each phrase might get decorated further with mustache and sprintf expressions:

1{
2    "example":"[0] %s is zero rule for {{me}}|[2,5] %s is between two and five for {{me}}|and a catchall rule for {{me}} to get my number %s"
3}

will put (as taken from tests):

1// will always use a found catchall
2__('example', {me: 'marcus'}) // --> and a catchall rule for marcus to get my number %s
3__('example', ['one'], {me: 'marcus'}) // --> and a catchall rule for marcus to get my number one
4
5// will search a matching interval or fallback to catchall
6__n('example', 1, {me: 'marcus'}) // --> and a catchall rule for marcus to get my number 1
7__n('example', 2, {me: 'marcus'}) // --> 2 is between two and five for marcus
8__n('example', 5, {me: 'marcus'}) // --> 5 is between two and five for marcus
9__n('example', 3, {me: 'marcus'}) // --> 3 is between two and five for marcus
10__n('example', 6, {me: 'marcus'}) // --> and a catchall rule for marcus to get my number 6

Notice: the "example" object in your json doesn't use any "one", "other" subnodes although you could use and even combine them. Currently "one" referres to the value of exactly 1 while "other" referres to every other value (think of 0, -10, null, false)

variable support

you might even use dynamic variables as they get interpreted on the fly. Better make sure no user input finds it's way to that point as they all get added to the en.js file if not yet existing.

1var greetings = ['Hi', 'Hello', 'Howdy']
2for (var i = 0; i < greetings.length; i++) {
3  console.log(__(greetings[i]))
4}

which puts

Hi
Hello
Howdy

Object notation

In addition to the traditional, linear translation lists, i18n also supports hierarchical translation catalogs.

To enable this feature, be sure to set objectNotation to true in your configure() call. Note: If you can't or don't want to use . as a delimiter, set objectNotation to any other delimiter you like.

Instead of calling __("Hello") you might call __("greeting.formal") to retrieve a formal greeting from a translation document like this one:

1{
2  "greeting": {
3    "formal": "Hello",
4    "informal": "Hi",
5    "placeholder": {
6      "formal": "Hello %s",
7      "informal": "Hi %s"
8    }
9  }
10}

In the document, the translation terms, which include placeholders, are nested inside the "greeting" translation. They can be accessed and used in the same way, like so __('greeting.placeholder.informal', 'Marcus').

Pluralization

Object notation also supports pluralization. When making use of it, the "one" and "other" entries are used implicitly for an object in the translation document. For example, consider the following document:

1{
2  "pets": {
3    "cat": {
4      "one": "Katze",
5      "other": "Katzen"
6    }
7  }
8}

When accessing these, you would use __n("pets.cat", "pets.cat", 3) to tell i18n to use both the singular and plural form of the "cat" entry. Naturally, you could also access these members explicitly with __("pets.cat.one") and __("pets.cat.other").

Defaults

When starting a project from scratch, your translation documents will probably be empty. i18n takes care of filling your translation documents for you. Whenever you use an unknown object, it is added to the translation documents.

By default, when using object notation, the provided string literal will be inserted and returned as the default string. As an example, this is what the "greeting" object shown earlier would look like by default:

1{
2  "greeting": {
3    "formal": "greeting.formal",
4    "informal": "greeting.informal"
5  }
6}

In case you would prefer to have a default string automatically inserted and returned, you can provide that default string by appending it to your object literal, delimited by a :. For example:

1__('greeting.formal:Hello')
2__('greeting.placeholder.informal:Hi %s')

Storage

Will get modular support for different storage engines, currently just json files are stored in filesystem.

json file

the above will automatically generate a en.json by default inside ./locales/ which looks like

1{
2  "Hello": "Hello",
3  "Hello %s, how are you today?": "Hello %s, how are you today?",
4  "weekend": "weekend",
5  "Hello %s, how are you today? How was your %s.": "Hello %s, how are you today? How was your %s.",
6  "Hi": "Hi",
7  "Howdy": "Howdy",
8  "%s cat": {
9    "one": "%s cat",
10    "other": "%s cats"
11  },
12  "There is one monkey in the %%s": {
13    "one": "There is one monkey in the %%s",
14    "other": "There are %d monkeys in the %%s"
15  },
16  "tree": "tree",
17  "%s dog": {
18    "one": "one dog",
19    "other": "[0] no dog|[2,5] some dogs|[6,11] many dogs|[12,36] dozens of dogs|a horde of %s dogs"
20  }
21}

that file can be edited or just uploaded to webtranslateit for any kind of collaborative translation workflow:

1{
2  "Hello": "Hallo",
3  "Hello %s, how are you today?": "Hallo %s, wie geht es dir heute?",
4  "weekend": "Wochenende",
5  "Hello %s, how are you today? How was your %s.": "Hallo %s, wie geht es dir heute? Wie war dein %s.",
6  "Hi": "Hi",
7  "Howdy": "Hallöchen",
8  "%s cat": {
9    "one": "%s Katze",
10    "other": "%s Katzen"
11  },
12  "There is one monkey in the %%s": {
13    "one": "Im %%s sitzt ein Affe",
14    "other": "Im %%s sitzen %d Affen"
15  },
16  "tree": "Baum",
17  "%s dog": {
18    "one": "Ein Hund",
19    "other": "[0] Kein Hund|[2,5] Ein paar Hunde|[6,11] Viele Hunde|[12,36] Dutzende Hunde|Ein Rudel von %s Hunden"
20  }
21}

Logging & Debugging

Logging any kind of output is moved to debug module. To let i18n output anything run your app with DEBUG env set like so:

1$ DEBUG=i18n:* node app.js

i18n exposes three log-levels:

• i18n:debug
• i18n:warn
• i18n:error

if you only want to get errors and warnings reported start your node server like so:

1$ DEBUG=i18n:warn,i18n:error node app.js

Combine those settings with you existing application if any of you other modules or libs also uses debug

Using custom logger

You can configure i18n to use a custom logger. For example attach some simple console-logging:

1i18n.configure({
2  // setting of log level DEBUG - default to require('debug')('i18n:debug')
3  logDebugFn: function (msg) {
4    console.log('debug', msg)
5  },
6
7  // setting of log level WARN - default to require('debug')('i18n:warn')
8  logWarnFn: function (msg) {
9    console.log('warn', msg)
10  },
11
12  // setting of log level ERROR - default to require('debug')('i18n:error')
13  logErrorFn: function (msg) {
14    console.log('error', msg)
15  }
16})

Test

1npm test

Roadmap

• add a storage adapter (to support .yaml, .js, memory)
• improved fallbacks
• refactor dot notation (ie. configurable delimiters)
• refactor to ES6
• refactor to standard + prettier
• move docs + examples to github pages

Changelog

For current release notes see GitHub Release Notes. Changes until 0.8.3 are filed as Changelog Summary.