madlib-locale

0.4.7 • Public • Published

madlib-locale

npm version David dependency drift detection

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;

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

Package Sidebar

Install

npm i madlib-locale

Weekly Downloads

2

Version

0.4.7

License

BSD-3-Clause

Unpacked Size

198 kB

Total Files

31

Last publish

Collaborators

  • cueedee