dust-intl

Dust helpers for internationalization.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
dust-intl
4891.1.17 years ago8 years agoMinified + gzip package size for dust-intl in KB

Readme

Dust Intl
Dust helpers for internationalization.
!npm Versionnpm-badgenpm !Build Statustravis-badgetravis !Dependency Statusdavid-badgedavid
Sauce Test Status
This package used to be named dust-helper-intl.

Overview

Goals

  • Integrate internationalization features with Dust to lower the barrier for localizing Dust templates.

  • Build on current and emerging JavaScript IntlIntl standards — architect in a future-focused way. Leverage industry standards used in other programming langages like CLDR locale data, and ICU Message syntaxICU.

  • Run in both Node.js and in the browser.

How It Works

Template Source:
<b>Price:</b> {@formatNumber val=price style="currency" currency="USD"/}

Render Template:
var context = {
    intl: {
        locales: 'en-US'
    },
    price: 1000
};

dust.renderSource(template, context, function(err, html) {
    console.log(html);
});

Output:
<b>Price:</b> $1,000.00

Features



Usage

Intl Dependency

This package assumes that the IntlIntl global object exists in the runtime. Intl is present in all modern browsers except Safari, and there's work happening to integrate Intl into Node.jsIntl-Node.
Luckly, there's the Intl.js polyfill! You will need to conditionally load the polyfill if you want to support runtimes which Intl is not already built-in.

Loading Intl.js Polyfill in a browser

If the browser does not already have the Intl APIs built-in, the Intl.js Polyfill will need to be loaded on the page along with the locale data for any locales that need to be supported:
<script src="intl/Intl.min.js"></script>
<script src="intl/locale-data/jsonp/en-US.js"></script>

Note: Modern browsers already have the Intl APIs built-in, so you can load the Intl.js Polyfill conditionally, by for checking for window.Intl.

Loading Intl.js Polyfill in Node.js

Conditionally require the Intl.js Polyfill if it doesn't already exist in the runtime. As of Node <= 0.10, this polyfill will be required.
if (!global.Intl) {
    require('intl');
}

Note: When using the Intl.js Polyfill in Node.js, it will automatically load the locale data for all supported locales.

Registering Helpers in a Browser

First, load Dust and this package onto the page:
<script src="dustjs/dust-core.min.js"></script>
<script src="dust-intl/dust-intl.min.js"></script>

By default, Handlebars Intl ships with the locale data for English built-in to the runtime library. When you need to format data in another locale, include its data; e.g., for French:
<script src="dust-intl/locale-data/fr.js"></script>

Note: All 150+ locales supported by this package use their root BCP 47 langage tag; i.e., the part before the first hyphen (if any).
Then, register the helpers with Dust:
DustIntl.registerWith(Dust);

This package will create the DustIntl global that has the registerWith() function.

Registering Helpers in Node.js

Import Dust and this package, then register the Intl helpers with Dust:
var Dust     = require('dustjs-linkedin'),
    DustIntl = require('dust-helper-intl');

DustIntl.registerWith(Dust);

Note: in Node.js, the data for all 150+ locales is pre-loaded and does not need to be loaded manually.

Supplying i18n Data to Dust

Dust has just the
context in which to pass all information. This package looks in the intl key in the context for the i18n used by the helpers.

context.intl.locales

A string with a BCP 47 language tag, or an array of such strings; e.g., "en-US". If you do not provide a locale, the default locale will be used, but you should always provide one!
This value is used by the helpers when constructing the underlying formatters.

context.intl.messages

This is an object the keys of which identify messages and the values are the messages themselves. These messages are referenced by the _key parameter of the {@intlMessage} helper. One common use is to put complex message strings here. The strings should be appropriate for the locale specified by context.intl.locales.
Note: These messages need to follow the ICU MessageICU standard. Luckily this is a common standard that professional translators should already be familiar with.
// Static collection of messages, per-locale.
var MESSAGES = {
    whoHosted: '{hostName} hosted the party!',
    petUpsell: 'Pets? We have: {numPets, number, integer}',
    ...
}

These statically defined message strings can be provided to dust via context.intl.messages:
// Supply the intl data as part of the context.
var context = {
    intl: {
        locales: 'en-US',
        messages: MESSAGES
    },
    ...
};

dust.renderSource(template, context, function(err, html) {
    console.log(html);
});

context.intl.formats

Object with user defined options for format styles. This is used to supply custom format styles and is useful you need supply a set of options to the underlying formatter; e.g., outputting a number in USD:
{
    number: {
        USD: {
            style   : 'currency',
            currency: 'USD'
        }
    },

    date    : {...},
    time    : {...},
    relative: {...}
}

These pre-defined formats map to their respective helpers of the same type, and all context.intl.formats are used by the {@formatNumber}, {@formatDate}, and {@formatTime} helpers. They can then be used by String name/path like this:
{@formatNumber val=100 formatName="USD"/}

Helpers

{@intl}

Block helper used to create a new intl data scope by updating the i18n data supplied to Dust within the block. This is useful when you need to render part of the page in a particular locale, or need to supply the i18n data to Dust via the template context.
The following example uses {@intl} to set the locale to French and will output "1 000":
{@intl locales="fr-FR"}
    {@formatNumber val=1000/}
{/intl}

{@formatDate}

Formats dates using Intl.DateTimeFormatIntl-DTF, and returns the formatted string value.
{@formatDate val=now weekday="long" timeZone="UTC"/}

var context = {
    intl: {
        locales: 'en-US'
    },
    now: Date.now()
};

Dust.renderSource(template, context, function(err, html) {
    console.log(html); // => "Tuesday, August 12, 2014"
});

Parameters:
  • val: Date instance or String timestamp to format.

  • [format]: Optional String path to a predefined format on context.intl.formats. The format's values are merged with other parameters.

Other parameters passed to this helper become the options argument when the Intl.DateTimeFormatIntl-DTF instance is created.

{@formatTime}

This delegates to the {@formatDate} helper, but first it will reference any formatName from context.intl.formats.time.

{@formatRelative}

Formats dates relative to "now" using IntlRelativeFormatIntl-RF, and returns the formatted string value.
<p>Posted {@formatRelative val=postDate/}</p>

var context = {
    intl: {
        locales: 'en-US'
    },
    postDate: Date.now() - (1000 * 60 * 60 * 24)  // 1 day ago.
};

Dust.renderSource(template, context, function(err, html) {
    console.log(html); // => "<p>Posted yesterday</p>"
});

Parameters:
  • val: Date instance or String timestamp to format.

  • [format]: Optional String path to a predefined format on context.intl.formats. The format's values are merged with other parameters.

Other parameters passed to this helper become the options argument when the Intl.DateTimeFormatIntl-DTF instance is created.

{@formatNumber}

Formats numbers using Intl.NumberFormatIntl-NF and returns the formatted string value.
{@formatNumber val=price style="currency" currency="USD"/}

var context = {
    intl: {
        locales: 'en-US'
    },
    price = 100
};

Dust.renderSource(template, context, function(err, html) {
    console.log(html); // => "$100.00"
});

Parameters:
  • val: Number to format.

  • [format]: Optional String path to a predefined format on context.intl.formats. The format's values are merged with other parameters.

Other parameters passed to this helper become the options argument when the Intl.NumberFormatIntl-NF instance is created.

{@formatMessage}

Formats ICU MessageICU strings with the given values supplied as the hash arguments.
You have {numPhotos, plural,
    =0 {no photos.}
    =1 {one photo.}
    other {# photos.}}

{@formatMessage _key="photos" numPhotos=numPhotos/}

var context = {
    intl: {
        locales: 'en-US',
        messages: {
            photos: '...', // String from code block above.
            ...
        },
        numPhotos: 1
    }
};

Dust.renderSource(template, context, function(err, html) {
    console.log(html); // => "You have one photo."
});

Parameters:
The parameters represent the name/value pairs that are used to format the message by providing values for its argument placeholders. A few parameters have special meaning and are used by this helper.


Note: It is recommended to use _key instead of including the literal message string in the template.

License

This software is free to use under the Yahoo! Inc. BSD license. See the LICENSE fileLICENSE for license text and copyright information.