Nunjucks Intl
This library provides Nunjucks helpers for internationalization. The helpers provide a declarative way to format dates, numbers, and string messages with pluralization support.
Overview
Nunjucks Intl uses FormatJS components under the hood, the docs can be found on the webiste: http://formatjs.io/
Features
- Display numbers with separators.
- Display dates and times correctly.
- Display dates relative to "now".
- Pluralize labels in strings.
- Support for 200+ languages.
- Runs in the browser and Node.js.
- Built on standards.
Quick example
{{ formatMessage(
intlGet("messages.post.meta"),
{
num: post.comments.length,
ago: formatRelative(post.date)
})
}}
var data = {
post: {
date : 1422046290531,
comments: [/*...*/]
}
};
var intlData = {
locales : ['en-US'],
messages: {
post: {
meta: 'Posted {ago}, {num, plural, one{# comment} other{# comments}}'
}
}
};
data.intl = intlData;
var html = nunjucks.renderString(/* Template source above */, data);
This example would render: "Posted 3 days ago, 1,000 comments" to the html
variable.
The post.meta
message is written in the industry standard ICU Message syntax, which you can
also learn about on the FormatJS website.
In all examples below, for simplicity, nunjucks.renderString is used, but, of course, template render() works the same way.
API Methods
Registering Nunjucks Intl with Nunjucks instance
To start using intl helpers in your template, first of all, you need to register helpers with your instance of Nunjucks enviroment.
This is done by:
const nunjucks = require('nunjucks');
const env = nunjucks.configure();
const nunjucksIntl = require('nunjucks-intl');
nunjucksIntl.registerWith(env);
This adds a few global functions to nunjucks enviroment, so you can use them in your templates. Nunjucks Intl
helpers expect to find intl
hash-map in template context data. More info below.
intlGet helper
This helper implements a lookup process by path to access data from the intl object passed into the Nunjucks data context when rendering the template. Usually this helper is used in a subexpressions to lookup translated string messages;
Nunjucks.renderString('{{ formatMessage(intlGet("MSG"), { firstName: firstName, lastName: lastName }) }}',
{
firstName: 'Vasiliy',
lastName : 'Pupkin',
intl: {
MSG : 'Hi, my name is {firstName} {lastName}.',
locales: 'en-US'
}
})
// output: Hi, my name is Vasiliy Pupkin.
formatNumber helper
This helper is used to format numbers, including currencies and percentages.
Nunjucks.renderString('{{ formatNumber(NUM)}}', { NUM: 4.004, intl: { locales: 'en-US' }})
// output: 4.004
Nunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 4.004, intl: { locales: 'de-DE' }})
// output: 4,004
Nunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 40000, intl: { locales: 'en-US' }})
// output: 40,000
Nunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 40000, intl: { locales: 'de-DE' }})
// output: 40.000
Nunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 40000.004, intl: { locales: 'en-US' }})
// output: 40,000.004
Nunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 40000.004, intl: { locales: 'de-DE' }})
// output: 40.000,004
Nunjucks.renderString('{{ formatNumber(40000, { style: "currency", currency: "USD" }) }}', { intl: { locales: 'en-US' }})
// output: $40,000.00
Nunjucks.renderString('{{ formatNumber(40000, { style: "currency", currency: "EUR", currencyDisplay: "code" }) }}', { intl: { locales: 'en-US' }})
// output: EUR40,000.00
// also it's possible to return a currency even when using a different locale
Nunjucks.renderString('{{ formatNumber(40000, { style: "currency", currency: CURRENCY }) }}', { CURRENCY: 'JPY', intl: { locales: 'de-DE' }})
// output: 40.000 ¥
Nunjucks.renderString('{{ formatNumber(0.45, { style: "percent" }) }}', { intl: { locales: 'en-US' }})
// output: 45%
formatDate/formatTime helpers
This helpers are used to format dates, including time. You can pass a date string or timestamp. formatDate and formatTime works the same way, and the only difference is the place for searching custom formats. formatDate search them in formats.date, and formatTime - in formats.time respectively. In example below, custom format is used, read more on FormatJS site.
var dateStr = 'Thu Jan 23 2014 18:00:44 GMT-0500 (EST)';
var timeStamp = 1390518044403; //same as dateStr
var intlData = {
locales: 'en-US',
formats: {
date: {
short: {
day: "numeric",
month: "numeric",
year: "numeric"
}
},
usual: {
hour: "numeric",
minute: "numeric",
timeZone: "UTC"
}
}
};
Nunjucks.renderString('{{ formatDate("' + dateStr + '") }}', { intl: { locales: 'en-US' }});
// output: 1/24/2014
//The same output using custom format
Nunjucks.renderString('{{ formatDate("' + dateStr + '", "short") }}', { intl: intlData });
// output: 1/24/2014
//timestamp is passed as a number
Nunjucks.renderString('{{ formatDate(' + timeStamp + ') }}', { intl: { locales: 'en-US' }});
// output: 1/24/2014
Nunjucks.renderString('{{ formatDate(' + timeStamp + ', "usual") }}', { intl: intlData });
// output: 11:00 PM
formatRelative helper
This helper is used to format relative date and time.
var tomorrow = new Date().getTime() + (24 * 60 * 60 * 1000);
Nunjucks.renderString('{{ formatRelative(date) }}', { date: tomorrow, intl: { locales: 'en-US' }});
// output: tomorrow
Nunjucks.renderString('{{ formatRelative(date, { style: "numeric" }) }}', { date: tomorrow, intl: { locales: 'en-US' }})
// output: in 1 day
// also it's possible to set NOW
Nunjucks.renderString('{{ formatRelative(2000, { now: 1000 }) }}', { intl: { locales: 'en-US' }});
// output: in 1 second
Nunjucks.renderString('{{ formatRelative(0, { now: 1000 }) }}', { intl: { locales: 'en-US' }});
// output: 1 second ago
formatMessage/formatHTMLMessage helpers
This helpers are used to format internationalization messages, including dates, numbers, and pluralization cases. Using formatHTMLMessage, you can pass messages with html entities, and they will not be escaped. User data is always escaped.
Nunjucks.renderString('{{ formatMessage({ firstName: firstName, lastName: lastName, intlName: "MSG" }) }}',
{
firstName: 'Vasiliy',
lastName : 'Pupkin',
intl: {
MSG : 'Hi, my name is {firstName} {lastName}.',
locales: 'en-US'
}
});
// output: Hi, my name is Vasiliy Pupkin.
Nunjucks.renderString('{{ formatMessage(POP_MSG, { city: city, population: population, census_date: census_date, timeZone: timeZone }) }}',
{
POP_MSG : '{city} has a population of {population, number, integer} as of {census_date, date, long}.',
city : 'Atlanta',
population : 5475213,
census_date: (new Date('1/1/2010')).getTime(),
timeZone : 'UTC',
intl: { locales: 'en-US' }
});
// output: Atlanta has a population of 5,475,213 as of January 1, 2010.
Nunjucks.renderString('{{ formatMessage(BDAY_MSG, { year: year }) }}',
{
BDAY_MSG: 'This is my {year, selectordinal, one{#st} two{#nd} few{#rd} other{#th}} birthday.',
year : 3,
intl: { locales: 'en-US' }
});
// output: This is my 3rd birthday.
Nunjucks.renderString('{{ formatHTMLMessage(intlGet("MSG"), { firstName: firstName, lastName: lastName }) }}',
{
firstName: '<Vasiliy>',
lastName : '<Pupkin>',
intl: {
MSG : 'Hi, my <name> is {firstName} {lastName}.',
locales: 'en-US'
}
});
// output: Hi, my <name> is <Vasiliy> <Pupkin>.
Also, you can lookup into tests for more usage examples.
Contribute
Let's make Nunjucks Intl and FormatJS better! If you're interested in helping, all contributions are welcome and appreciated. Nunjucks Intl is just one of many packages that make up the FormatJS suite of packages, and you can contribute to any/all of them, including the Format JS website itself.
License
This software is free to use under the BSD license. See the LICENSE file for license text and copyright information.