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
}