polyglot v0.5.0

Polyglot

Polyglot is an internationalization library for express. It's template-agnostic, based on JSON files, and less than 200 lines of code. Compatible with express 3+.

Usage

Install with npm install polyglot:

var i18n = require('polyglot')

app = express()

app.use(express.cookieParser())
app.use(express.cookieSession())
app.use(i18n())

# register template locals
app.locals(i18n.locals)

Check the example app.

Options

app.use(i18n({
    debug   : false    // enable debug messages
  , default : 'en'     // default language
  , path    : '/lang'  // path for .json language files
}))

Language files

Translation files are .json files containing the translated strings. The default directory is /lang. To add a new language, just create an empty .json file with the language code as it's name (i.e. de.json).

See https://github.com/ricardobeat/node-polyglot/blob/master/example/lang/pt.json

String definitions are automatically added to all available languages by adding the updateStrings middleware to your express config:

app.configure('development', function(){
    app.use(i18n.updateStrings)
})

Templating / locals

All the following examples are based on handlebars templates.

Registering app.locals(i18n.locals) is simply a shortcut for:

app.locals({
    __        : i18n.translate
  , _n        : i18n.plural
  , languages : i18n.languages
})

In addition to that, i18n() registers a middleware which sets req.lang and req.locale containing the user's settings.

See the /example folder for an implementation using Handlebars helpers.

i18n.translate

Takes a string and returns a translation based on your current session preferences (req.session.lang)`.

 {{ __('hello') }}
 // en: 'hello'
 // pt: 'olá'

i18n.plural

Takes [n, singular, plural] or [n, zero, singular, plural] arguments. Using i18n.translate with the same arguments will use plural automatically.

{{ __(1, "%s cat", "%s cats") }}
// en: '1 cat'
// pt: '1 gato'

{{ __(0, "no cats", "%s cat", "%s cats") }}
// en: 'no cats'
// pt: 'nenhum gato'

i18n.setLanguage

To change the current language call i18n.setLanguage, passing the user's session object and desired language code:

app.get('/lang/:lang', function(req, res){
    i18n.setLanguage(req.session, req.params.lang)
    res.redirect(req.headers.referer || '/')
})

Accessing http://yourapp/lang/de will set language to de, if it is defined in the i18n.languages object.

Source code and tests

Polyglot is written in coffeescript and distributed in js. Read the annotated source here.

Run tests using mocha or npm test. You need coffee-script and mocha installed globally on your machine.