locality v0.0.6

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
}