Madlib-locale NPM

madlib-locale

A Handlebars.js helper collection providing keyed dictionary substitution and simple localization.

It can format numbers, money, dates, and "translate" texts using the following packages:

Installing

npm install handlebars --save
npm install madlib-locale --save

Using

madlib-locale's single export is the localeManager object, which will need to be initialize( ... )-ed before use. initialize( ... ) returns a (Q) Promise that'll be fullfilled when the specified locale's definition file has been loaded; it takes in three parameters:

The Handlebars- (or hbsfy runtime that is to be extended with madlib-locale's helpers;
The locale, expressed as a valid BCP 47 language tag string; It'll designate a .json locale definition file by the same name that is to be loaded;
An optional url base path to retrieve that- and any future locale definition files from; it defaults to './i18n';

Handlebars      = require( 'handlebars/runtime' )
localeManager   = require( 'madlib-locale' )

localeManager
    .initialize( Handlebars, 'en-GB', '/examples' )
    .then(

        () ->

            ##  Ready to render templates using the helper functions

            return

        () ->

            console.error( 'something went wrong...' )
            return
    )
    .done()

Change the locale

The locale can be changed at any time through invoking localeManager.setLocale( ... ); it, too, will return a Promise. Once resolved, a re-rendering of your templates will ensure they'll be in the new locale.

localeManager
    .setLocale( 'nl-NL' )
    .then(

        () ->

            ##  Ready to re-render templates using the helper functions

            return

        () ->
            console.error( 'something went wrong...' )
            return
    )

Get the current locale name

To retrieve the current locale name:

    console.log( "Current locale: #{ localeManager.getLocaleName() }" )

Set up a locale definition file

At its top level, a locale definition file has a name string, and phrases- and formatting objects.

name is expected to be a valid BCP 47 language tag string. This is also the name of the file (excluding the .json filename extension);
phrases is any object acceptable as a phrases dictionary to node-polyglot;
formatting should contain three further sections:
- datetime is a keyword-to-Moment format( ... ) argument-mapping. The examples unimaginatively sport descriptive identifying keywords like date and datetime but you can name them whatever you like;
- money, similary, is a keyword-to-Accounting formatMoney( ... ) arguments-mapping, expecting only sign (currency symbol) and precision arguments. The arguments for thousands- and decimal separator markers being taken from the number definition below;
- number is an object defining the decimalMarker, thousandMarker and (default) precision arguments to the Accounting formatNumber( ... ) method;

Use from your Handlebars templates

Translate: t or T
- ... without interpolation
  These helpers take one argument which should be a key into the phrases dictionary in your locale definition file:
```
<ul>
    <li>{{T 'an.entry.in.your.phrases.dictionary'}}</li>
    <li>{{t 'another.entry.in.your.phrases.dictionary'}}</li>
</ul>
```
  The difference between T and t is that the former additionally does first-letter capitalization of the dictionary's value.
  A longer form alternative to t which madlib-locale has historically provided is _translate. It does not have a capitalization variant.
- ... with interpolation
  These helpers also support node-polyglot's interpolation; any additional positional arguments will be interpolated into the resulting dictionary value string as follows:
```
{
    "phrases": {
        "the.phrases.dictionary.values.can.be.X.with.Y":    "translation strings can be %{0} with anything, like: \"%{1}\""
    ,   "can.be.interpolated":                              "interpolated"
    }
}
```
```
{{T 'the.phrases.dictionary.values.can.be.X.with.Y' (t 'can.be.interpolated') some.example.value }}
```
- ... with named parameters
  Interpolations with named instead of positional parameters are also possible:
```
{
    "phrases": {
        "the.phrases.dictionary.values.can.be.X.with.Y":    "translation strings can be %{foo} with anything, like: \"%{bar}\""
    ,   "can.be.interpolated":                              "interpolated"
    }
}
```
```
{{T 'the.phrases.dictionary.values.can.be.X.with.Y' foo=(t 'can.be.interpolated') bar=some.example.value }}
```
- ... with pluralization
  Using the special named parameter smart_count you can leverage node-polyglot's pluralization mechanism:
```
{
    "phrases": {
        "some.mice":    "a mouse |||| some mice"
    }
}
```
```
{{T 'some.cars' smart_count=1 }}
{{T 'some.cars' smart_count=42 }}
```
  Note that even though node-polyglot does allow interpolation of the smart_count value, it will not receive any localized formatting treatment.
Date: D
This helper takes two arguments:
- A key into the formatting.datetime section of your locale definition file, designating the specific format to use;
- Ideally a Moment instance, but any value that the Moment constructor can grok as its argument should be fine.
```
<dl>
    <dt>{{T 'the.date'}}</dt>
    <dd>{{D 'date' some.moment.compatible.value.to.be.formatted.as.a.date.string }}</dd>

    <dt>{{T 'the.datetime'}}</dt>
    <dd>{{D 'datetime' some.moment.compatible.value.to.be.formatted.as.a.date-and-time.string }}</dd>
</ul>
```
A longer form alternative to D which madlib-locale has historically provided is _date.
Number: N
This helper takes one or two arguments:
- A number value to be formatted;
- An, optional, precision argument designating the specific number of decimals to format instead of the current locale definition's default.
```
<ol>
    <li>{{N some.value.to.be.formatted.as.a.number.with.default.precision }}</li>
    <li>{{N some.value.to.be.formatted.as.a.number.with.alternative.precision 7 }}</li>
<ol>
```
A longer form alternative to N which madlib-locale has historically provided is _number.
Money
This helper takes two arguments:
- A key into the formatting.money section of your locale definition file, designating the specific currency to use, or simply default if the current locale defintion's default currenct is desired;
- A number value to be formatted as an amount, currency symbol included;
```
{{M 'euro' some.value.to.be.formatted.as.a.amount.of.money }}
```
A longer form alternative to M which madlib-locale has historically provided is _money.