dust-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

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

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

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

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

Features

• Formats numbers and dates/times, including those in complex messages using the JavaScript built-ins: Intl.NumberFormatIntl-NF and Intl.DateTimeFormatIntl-DTF, respectively.

• Formats relative times (e.g., "3 hours ago") using the Intl RelativeFormatIntl-RF library which uses CLDR locale data.

• Formats complex messages, including plural and select arguments using the Intl MessageFormatIntl-MF library which uses CLDR locale data and works with ICU Message syntaxICU.

Usage

Intl Dependency

<script src="intl/Intl.min.js"></script>
<script src="intl/locale-data/jsonp/en-US.js"></script>

if (!global.Intl) {
    require('intl');
}

<script src="dustjs/dust-core.min.js"></script>
<script src="dust-intl/dust-intl.min.js"></script>

<script src="dust-intl/locale-data/fr.js"></script>

DustIntl.registerWith(Dust);

var Dust     = require('dustjs-linkedin'),
    DustIntl = require('dust-helper-intl');

DustIntl.registerWith(Dust);

// Static collection of messages, per-locale.
var MESSAGES = {
    whoHosted: '{hostName} hosted the party!',
    petUpsell: 'Pets? We have: {numPets, number, integer}',
    ...
}

// 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

{
    number: {
        USD: {
            style   : 'currency',
            currency: 'USD'
        }
    },

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

{@formatNumber val=100 formatName="USD"/}

Helpers

{@intl}

{@intl locales="fr-FR"}
    {@formatNumber val=1000/}
{/intl}

{@formatDate}

{@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"
});

• 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.

{@formatTime}

{@formatRelative}

<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>"
});

• 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.

{@formatNumber}

{@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"
});

• 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.

{@formatMessage}

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."
});

• _msg: String message or IntlMessageFormatIntl-MF instance to format with the given parameters as the values.

• _key: String to lookup the message in context.intl.messages.

License