rendr-i18n v0.0.5

Rendr-i18n

Rendr-18n provides an easy way to manage localization using Rendr. By default it will look in the locale folder in the base directory of your Rendr project for the language based on some session key set on the request object. It will then use that language to add the appropriate set of translations to your App model. Then using the handlebars helper {{t "some_key"}} you can easily localize your views.

###Install

npm install rendr-18n

###Using Rendr-18n

To add it to your project in index.js (or the file you use to start your server) after calling render.createServer initialize render-18n with the server object and an optional set of options.

Example:

var server = rendr.createServer({
  dataAdapterConfig: dataAdapterConfig
});

i18n.initialize(server, {..some options});

Next register the render-18n's handlebars helper to your client-side app in app/app.js.

Example:

i18nHandlebarsHelpers = require('../node_modules/rendr-i18n/i18n-handlebarsHelpers');

...

postInitialize: function() {
    this.templateAdapter.registerHelpers(handlebarsHelpers);
    i18nHandlebarsHelpers.call(this, this.templateAdapter.Handlebars);
},

That's it, you now have localization!

###Options

• sessionKeyString default session.language: Used to specify the path in which Rendr-18n should look for your language. The path should be a string representation of the path on the request object. Example: "session.language".
• generateBoolean default false: If set to true will auto-generate the localization directories if they do not exist with the default language as well as any additional languages passed in. Useful for quickly bootstrapping a project. For each language that's auto-generated an index.json file with an empty object generated as well.
• defaultLanguageString default en: The default language to use if none is provided or exists.
• languagesArray default []: An array of additional languages to generate. This array will be autopopulated with all languages that already have existing directories.
• localePathString default ./locale: the default path for Rendr-i18n to look for your translations.
• redisObject
  • write Boolean optional: If set to true when your server starts all local translations files are saved to Redis using HSET.
  • prefix String optional :a prefix to prepend to your HKEY for each language.
  • host String required : Your Redis host.
  • port Number required : Your Redis port.
  • password String optional : Your Redis password.

###About Storage

By default translations are stored in memory and retrieved when a user requests a page. While effective for development this may not be optimal for larger applications. Rendr-18n has a Redis option which will retrieve translations from Redis during a request minimizing the memory footprint on your node server. Here is an example of how to use Redis with Rendr-i18n:

i18n.initialize(server, {
  redis: {
    write : true,
    prefix: 'translations',
    host  : '127.0.0.1',
    port  : '6379'
  }
});

###About the Localization Directories

By default it's assumed all localization files will be located in a base directory locale. A directory should then exist for each language you would like to add to your project so English would be locale/en/ and French would be locale/fr/.

Inside each directory the base translation file is index.json. Any keys declared in this file will be used as is for your project. If you would like to add other files (such as one file per view) simply create a json file of any name. Any translations in this file will have the file name prepended to them to avoid conflicts. So for instance a page heading for page1 in page1.json would have the key "page1.heading" whereas the heading for page2 in page2.json would have the key "page2.heading". This allows for more consistent, symantic key names as oppose to having to do something like page1Heading, page2Heading.

###Using the Handlebars Helper

The handlebars helper only has one real requirement which is a key param passed in which matches the key of the translation you would like to use.

Basic Example:

{{t "my_key"}}

The helper can take as many params as you like however. Passed in params are swapped in in the order they're listed.

Example index.json in /locale/en/:

{
    "my_key": "Hello %name%, what's your favorite %food%?"
}

{{t "my_key" "Mark" "food"}}
{{! outputs "Hello Mark, what's your favorite food?"}}

You can use nested helpers as well. By default when values are added to the helper's hash it's assumed they're looking to be use in a handlebar helper. Note: This will trigger a recompilation after the original swap.

{{t "my_key" "{{somehelper my_name}}" my_name=name}}