Not a Package Manager

    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

    Install

    npm i madlib-locale

    DownloadsWeekly Downloads

    37

    Version

    0.4.7

    License

    BSD-3-Clause

    Unpacked Size

    198 kB

    Total Files

    31

    Last publish

    Collaborators

    • cueedee