Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/marviq/madlib-locale
Handlebars helpers for i18n and l10n
https://github.com/marviq/madlib-locale
accounting format handlebars handlebars-helpers i18n internationalization l10n localization moment polyglot translate translation
Last synced: about 5 hours ago
JSON representation
Handlebars helpers for i18n and l10n
- Host: GitHub
- URL: https://github.com/marviq/madlib-locale
- Owner: marviq
- License: bsd-3-clause
- Created: 2014-06-23T11:40:40.000Z (over 10 years ago)
- Default Branch: develop
- Last Pushed: 2020-10-05T06:32:14.000Z (about 4 years ago)
- Last Synced: 2024-11-14T13:42:54.324Z (6 days ago)
- Topics: accounting, format, handlebars, handlebars-helpers, i18n, internationalization, l10n, localization, moment, polyglot, translate, translation
- Language: CoffeeScript
- Homepage:
- Size: 454 KB
- Stars: 0
- Watchers: 8
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# madlib-locale
[](http://badge.fury.io/js/madlib-locale)
[](https://david-dm.org/marviq/madlib-locale)
A [`Handlebars.js`](https://github.com/wycats/handlebars.js#readme) helper collection providing keyed dictionary substitution and simple localization.
It can format numbers, money, dates, and "translate" texts using the following packages:
- [`accounting`](http://openexchangerates.github.io/accounting.js/)
- [`moment`](http://momentjs.com/)
- [`node-polyglot`](http://airbnb.io/polyglot.js/)
## Installing
```shell
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`](https://github.com/kriskowal/q#readme) that'll be fullfilled when the specified locale's definition file has been loaded; it takes in three
parameters:
* The [`Handlebars`-](http://handlebarsjs.com/installation.html#npm) (or [`hbsfy` runtime](https://github.com/epeli/node-hbsfy#helpers) that is to be
extended with `madlib-locale`'s helpers;
* The locale, expressed as a valid [BCP 47 language tag](https://tools.ietf.org/html/bcp47#section-2) 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'`;
```coffee
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.
```coffee
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:
```coffee
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](https://tools.ietf.org/html/bcp47#section-2) 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`](http://airbnb.io/polyglot.js/#translation);
* `formatting` should contain three further sections:
* `datetime` is a keyword-to-[`Moment` `format( ... )` argument](http://momentjs.com/docs/#/displaying/format/)-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](http://openexchangerates.github.io/accounting.js/#methods)-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( ... )`](http://openexchangerates.github.io/accounting.js/#methods) method;
See also the [examples](https://github.com/marviq/madlib-locale/tree/develop/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](#definition-phrases) in your locale
definition file:
```hbs
- {{T 'an.entry.in.your.phrases.dictionary'}}
- {{t 'another.entry.in.your.phrases.dictionary'}}
```
The difference between `T` and `t` is that the former additionally does
[first-letter capitalization](https://github.com/epeli/underscore.string#capitalizestring-lowercaserestfalse--string) 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](http://airbnb.io/polyglot.js/#interpolation); any additional _positional_ arguments will
be interpolated into the resulting dictionary value string as follows:
```json
{
"phrases": {
"the.phrases.dictionary.values.can.be.X.with.Y": "translation strings can be %{0} with anything, like: \"%{1}\""
, "can.be.interpolated": "interpolated"
}
}
```
```hbs
{{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:
```json
{
"phrases": {
"the.phrases.dictionary.values.can.be.X.with.Y": "translation strings can be %{foo} with anything, like: \"%{bar}\""
, "can.be.interpolated": "interpolated"
}
}
```
```hbs
{{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](http://airbnb.io/polyglot.js/#pluralization)
mechanism:
```json
{
"phrases": {
"some.mice": "a mouse |||| some mice"
}
}
```
```hbs
{{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`](#definition-datetime) section of your locale definition file, designating the specific format to use;
* Ideally a `Moment` instance, but any value that the [`Moment`](http://momentjs.com/docs/#/parsing/) constructor can grok as its argument should be
fine.
```hbs
- {{T 'the.date'}}
- {{D 'date' some.moment.compatible.value.to.be.formatted.as.a.date.string }}
- {{T 'the.datetime'}}
- {{D 'datetime' some.moment.compatible.value.to.be.formatted.as.a.date-and-time.string }}
- {{N some.value.to.be.formatted.as.a.number.with.default.precision }}
- {{N some.value.to.be.formatted.as.a.number.with.alternative.precision 7 }}
```
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.
```hbs
```
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`](#definition-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;
```hbs
{{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](./CONTRIBUTING.md).
## Changelog
See [CHANGELOG](./CHANGELOG.md) for versions >`0.2.1`; For older versions, refer to the
[releases on GitHub](https://github.com/marviq/madlib-locale/releases?after=v0.3.0) for a detailed log of changes.
## License
[BSD-3-Clause](./LICENSE)