| 1 | Polyglot
|
| 2 | ========
|
| 3 |
|
| 4 | Polyglot is an internationalization library for [express](http://github.com/visionmedia/express). It's template-agnostic, based on JSON files, and less than 200 lines of code. Compatible with express 3+.
|
| 5 |
|
| 6 | ## Usage
|
| 7 |
|
| 8 | Install with `npm install polyglot`:
|
| 9 |
|
| 10 | var i18n = require('polyglot')
|
| 11 |
|
| 12 | app = express()
|
| 13 |
|
| 14 | app.use(express.cookieParser())
|
| 15 | app.use(express.cookieSession())
|
| 16 | app.use(i18n())
|
| 17 |
|
| 18 | # register template locals
|
| 19 | app.locals(i18n.locals)
|
| 20 |
|
| 21 | Check the [example](https://github.com/ricardobeat/node-polyglot/tree/master/example) app.
|
| 22 |
|
| 23 | ### Options
|
| 24 |
|
| 25 | app.use(i18n({
|
| 26 | debug : false // enable debug messages
|
| 27 | , default : 'en' // default language
|
| 28 | , path : '/lang' // path for .json language files
|
| 29 | }))
|
| 30 |
|
| 31 | ### Language files
|
| 32 |
|
| 33 | 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`).
|
| 34 |
|
| 35 | See https://github.com/ricardobeat/node-polyglot/blob/master/example/lang/pt.json
|
| 36 |
|
| 37 | String definitions are automatically added to all available languages by adding the `updateStrings` middleware to your express config:
|
| 38 |
|
| 39 | app.configure('development', function(){
|
| 40 | app.use(i18n.updateStrings)
|
| 41 | })
|
| 42 |
|
| 43 | ### Templating / locals
|
| 44 |
|
| 45 | All the following examples are based on [handlebars](http://github.com/donpark/hbs) templates.
|
| 46 |
|
| 47 | Registering `app.locals(i18n.locals)` is simply a shortcut for:
|
| 48 |
|
| 49 | app.locals({
|
| 50 | __ : i18n.translate
|
| 51 | , _n : i18n.plural
|
| 52 | , languages : i18n.languages
|
| 53 | })
|
| 54 |
|
| 55 | In addition to that, `i18n()` registers a middleware which sets `req.lang` and `req.locale` containing the user's settings.
|
| 56 |
|
| 57 | See the `/example` folder for an implementation using Handlebars helpers.
|
| 58 |
|
| 59 | #### i18n.translate
|
| 60 |
|
| 61 | Takes a string and returns a translation based on your current session preferences (`req.session.lang`)`.
|
| 62 |
|
| 63 | {{ __('hello') }}
|
| 64 | // en: 'hello'
|
| 65 | // pt: 'olá'
|
| 66 |
|
| 67 | #### i18n.plural
|
| 68 |
|
| 69 | Takes `[n, singular, plural]` or `[n, zero, singular, plural]` arguments. Using `i18n.translate` with the same arguments will use plural automatically.
|
| 70 |
|
| 71 | {{ __(1, "%s cat", "%s cats") }}
|
| 72 | // en: '1 cat'
|
| 73 | // pt: '1 gato'
|
| 74 |
|
| 75 | {{ __(0, "no cats", "%s cat", "%s cats") }}
|
| 76 | // en: 'no cats'
|
| 77 | // pt: 'nenhum gato'
|
| 78 |
|
| 79 | #### i18n.setLanguage
|
| 80 |
|
| 81 | To change the current language call `i18n.setLanguage`, passing the user's session object and desired language code:
|
| 82 |
|
| 83 | app.get('/lang/:lang', function(req, res){
|
| 84 | i18n.setLanguage(req.session, req.params.lang)
|
| 85 | res.redirect(req.headers.referer || '/')
|
| 86 | })
|
| 87 |
|
| 88 | Accessing http://yourapp/lang/de will set language to `de`, *if* it is defined in the i18n.languages object.
|
| 89 |
|
| 90 | ### Source code and tests
|
| 91 |
|
| 92 | Polyglot is written in coffeescript and distributed in js. [Read the annotated source here](http://ricardobeat.github.com/node-polyglot).
|
| 93 |
|
| 94 | Run tests using `mocha` or `npm test`. You need `coffee-script` and `mocha` installed globally on your machine.
|