Locality

Locality adds i18n support to Express. It exposes middleware that can be added to the Express middleware stack.

Locality uses YAML configuration files to define it's language packs.

Definitions

First you must define your language packs. Language packs are directories named after the locale they are supporting, each file inside a locale directiory defines a namespace and each key within that namespace is a localized string.

/packs //The default language pack directory
en_US/default.yml //en_US is the locale and bar is the namespace

Hello {{name}}: 'Hello {{name}}'' //Locality supports Handlebars variables
//Locality supports pluralization
I ate %s duck:
    0: 'I ate no ducks' //You can provide number based keys which Locality will look for first, this helps with languages like Russian that have multiple types of pluralization
    singular: 'I ate %s duck' //Locality supports string formatting with sprintf-js
    plural: 'I ate %d ducks'

en_US/foo.yml

bar %s: 'bar %s'

Instantiation

You should instantiate Locality in your app.js, it should be done before you set Express' middleware.

var Locality = require('locality'),
    i18n = new Locality({
        path: './packs', //The path to the language packs directory
        defaultLocale: 'en_US', //The default locale
        defaultFile: 'default.yml' //The default file to use when translating strings
        locales: ['en_US'] //The supported locales, expects an array of locale strings
    });

Pass the Locality middleware anywhere in the middleware chain you want.

app.use(i18n.middleware());

Usage

The Locality object is attached to the Express' req object

var route = function (req, res, next) {
    
    req.i18n //The Locality object

    req.i18n.setLocale('en_US'); //Manually set the locale
    req.i18n.setLocaleFromHeaders(req.headers); //Set the locale from the 'accept-language' headers
    req.i18n.setLocaleFromCookie(req.cookies, 'lang');//Set the locale from the cookie, the second arg is the key to look for
    req.i18n.setLocaleFromQuery(req.query, 'lang'); //Set the locale from the query/body, the second arg is the key to look for
    req.i18n.setLocaleFromSubdomain(req.headers.host); //Set the locale from the subdomain of the url string

    req.i18n.getLocale(); //Returns the current locale

    //Translation for a single string
    req.i18n.__('Hello {{name}}', { name: 'Devon Anderson' }); //Looks in the default file (default.yml) returns Hello Devon Anderson
    req.i18n.__('foo.yml', 'bar %s', 'baz'); //Looks in foo.yml and returns bar baz

    //Pluralized translations, definitions needs to have a "singular" and "plural" set of keys, and can provide options number based keys.
    req.i18n.__p('I ate %s duck', 0); //I ate no ducks
    req.i18n.__p('I ate %s duck', 2); //I ate 2 ducks
    req.i18n.__p('I ate %s duck', 'a', 1); //I ate a duck
}