Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ksdaemon/nunjucks-intl
Nunjucks helpers for internationalization.
https://github.com/ksdaemon/nunjucks-intl
Last synced: 3 months ago
JSON representation
Nunjucks helpers for internationalization.
- Host: GitHub
- URL: https://github.com/ksdaemon/nunjucks-intl
- Owner: KSDaemon
- License: bsd-3-clause
- Created: 2016-01-02T10:00:03.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-01-08T17:37:12.000Z (about 2 years ago)
- Last Synced: 2024-09-24T07:21:40.331Z (4 months ago)
- Language: JavaScript
- Homepage: http://formatjs.io/nunjucks/
- Size: 3.93 MB
- Stars: 11
- Watchers: 3
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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.
[![NPM version][npm-image]][npm-url]
[![Build Status][gh-build-test-image]][gh-build-test-url]
[![Code coverage][coveralls-image]][coveralls-url]
[![MIT License][license-image]][license-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]
Overview
--------
Nunjucks Intl uses [FormatJS][] components under the hood, the docs can be found on the webiste:
### 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
```nunjucks
{{ formatMessage(
intlGet("messages.post.meta"),
{
num: post.comments.length,
ago: formatRelative(post.date)
})
}}
```
```js
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][FormatJS].
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:
```javascript
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;
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
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: '',
lastName : '',
intl: {
MSG : 'Hi, my is {firstName} {lastName}.',
locales: 'en-US'
}
});
// output: Hi, my is <Vasiliy> <Pupkin>.
```
Also, you can lookup into [tests](tests/helpers.js) 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][FormatJS GitHub], and you can contribute to any/all of them,
including the [Format JS website][FormatJS] itself.
License
-------
This software is free to use under the BSD license.
See the [LICENSE file][LICENSE] for license text and copyright information.
[Nunjucks]: http://mozilla.github.io/nunjucks
[npm-url]: https://www.npmjs.com/package/nunjucks-intl
[npm-image]: https://img.shields.io/npm/v/nunjucks-intl.svg?style=flat
[gh-build-test-url]: https://github.com/KSDaemon/nunjucks-intl/actions/workflows/build-and-test.yml
[gh-build-test-image]: https://github.com/KSDaemon/nunjucks-intl/actions/workflows/build-and-test.yml/badge.svg
[coveralls-url]: https://coveralls.io/github/KSDaemon/nunjucks-intl
[coveralls-image]: https://img.shields.io/coveralls/KSDaemon/nunjucks-intl/master.svg?style=flat
[license-image]: https://img.shields.io/badge/license-BSD-blue.svg
[license-url]: http://opensource.org/licenses/BSD-2-Clause
[snyk-image]: https://snyk.io/test/github/KSDaemon/nunjucks-intl/badge.svg?targetFile=package.json
[snyk-url]: https://snyk.io/test/github/KSDaemon/nunjucks-intl?targetFile=package.json
[FormatJS]: http://formatjs.io/
[FormatJS GitHub]: http://formatjs.io/github/
[ICU Message syntax]: http://formatjs.io/guide/#messageformat-syntax
[LICENSE]: https://github.com/KSDaemon/nunjucks-intl/blob/master/LICENSE