An internationalization library for node.js
CoffeeScript JavaScript HTML CSS
Latest commit a6c35fd Aug 7, 2015 @ricardobeat Merge pull request #8 from nmss/patch-1
Fix README typo
Failed to load latest commit information.
example Update example app Feb 17, 2013
src Pluggable storage engine, simplify code Feb 17, 2013
.npmignore Reorganize code using /src and /lib Feb 16, 2013
index.js Reorganize code using /src and /lib Feb 16, 2013
package.json Fixing the repo path. Former redirect not in place Oct 30, 2013


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


Install with npm install polyglot:

var i18n = require('polyglot')

app = express()


app.use(i18n())         # add middleware
app.locals(i18n.locals) # register template locals

Check the example app.


    debug   : false    // enable debug messages
  , default : 'en'     // default language
  , path    : '/lang'  // path for .json language files

Storage engines and language files

By default polyglot uses a JSON storage backend for translations, saving files to options.path (default: /lang). To add a new language, just create an empty .json file with the language code as it's name (e.g. de.json or 'en-UK.json'). These files can be sent to apps like for management and collaborative translation efforts.

See example/lang/pt.json for a sample.

String collection / auto-updating

String definitions are automatically added to all available languages by using the updateStrings middleware:

app.configure('development', function(){

Different storage backends (MongoDB, Redis) can be used by adding a constructor to and setting the store option:

function MongoStore () { ... } = MongoStore

    store: 'mongo'

This object must implement the load, save and update methods, and will receive the i18n object as first argument on initialization. See the source for the JSON storage engine at src/

Templating / locals

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

    __        : i18n.translate
  , _n        : i18n.plural
  , languages : i18n.languages

In addition to these locals, the i18n() middleware sets the req.lang and req.locale properties containing user settings.

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


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

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


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'


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

When accessing the language will be set to de, if it's in the available languages (i18n.languages) list.

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.


  • implement simple default backends for MongoDB/Redis/LevelDB
  • example of serving a string map to a client-side app
  • tiny library implementing translate and plural on the client, bundled with the string map and served at /polyglot/client.js
  • support different pluralization rules