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:

• accounting
• moment
• node-polyglot

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;

See also the examples on GitHub.

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.

Contributing

See CONTRIBUTING.

Changelog

See CHANGELOG for versions >0.2.1; For older versions, refer to the releases on GitHub for a detailed log of changes.

License

BSD-3-Clause