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 --savenpm 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
- (orhbsfy
runtime that is to be extended withmadlib-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 consoleerror '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 consoleerror 'something went wrong...' return
Get the current locale name
To retrieve the current locale name:
consolelog "Current locale: "
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 tonode-polyglot
;formatting
should contain three further sections:datetime
is a keyword-to-Moment
format( ... )
argument-mapping. The examples unimaginatively sport descriptive identifying keywords likedate
anddatetime
but you can name them whatever you like;money
, similary, is a keyword-to-Accounting
formatMoney( ... )
arguments-mapping, expecting onlysign
(currency symbol) andprecision
arguments. The arguments for thousands- and decimal separator markers being taken from thenumber
definition below;number
is an object defining thedecimalMarker
,thousandMarker
and (default)precision
arguments to theAccounting
formatNumber( ... )
method;
See also the examples on GitHub.
Use from your Handlebars templates
-
Translate:
t
orT
-
... 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
andt
is that the former additionally does first-letter capitalization of the dictionary's value.A longer form alternative to
t
whichmadlib-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:{{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:
{{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 leveragenode-polyglot
's pluralization mechanism:{{T 'some.cars' smart_count=1 }}{{T 'some.cars' smart_count=42 }}Note that even though
node-polyglot
does allow interpolation of thesmart_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 theMoment
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
whichmadlib-locale
has historically provided is_date
. - A key into the
-
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
whichmadlib-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 simplydefault
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
whichmadlib-locale
has historically provided is_money
. - A key into the
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.