{"id":15018104,"url":"https://github.com/ksdaemon/nunjucks-intl","last_synced_at":"2025-10-23T15:31:37.407Z","repository":{"id":3284428,"uuid":"48905613","full_name":"KSDaemon/nunjucks-intl","owner":"KSDaemon","description":"Nunjucks helpers for internationalization.","archived":false,"fork":false,"pushed_at":"2023-01-08T17:37:12.000Z","size":4123,"stargazers_count":11,"open_issues_count":1,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-23T10:42:22.794Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://formatjs.io/nunjucks/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KSDaemon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-02T10:00:03.000Z","updated_at":"2023-01-19T16:07:52.000Z","dependencies_parsed_at":"2023-01-12T15:01:16.100Z","dependency_job_id":null,"html_url":"https://github.com/KSDaemon/nunjucks-intl","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KSDaemon%2Fnunjucks-intl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KSDaemon%2Fnunjucks-intl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KSDaemon%2Fnunjucks-intl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KSDaemon%2Fnunjucks-intl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KSDaemon","download_url":"https://codeload.github.com/KSDaemon/nunjucks-intl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237852328,"owners_count":19376656,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:51:27.403Z","updated_at":"2025-10-23T15:31:31.647Z","avatar_url":"https://github.com/KSDaemon.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Nunjucks Intl\n=============\n\nThis library provides [Nunjucks][] helpers for internationalization. The helpers provide a declarative way\nto format dates, numbers, and string messages with pluralization support.\n\n[![NPM version][npm-image]][npm-url]\n[![Build Status][gh-build-test-image]][gh-build-test-url]\n[![Code coverage][coveralls-image]][coveralls-url]\n[![MIT License][license-image]][license-url]\n[![Known Vulnerabilities][snyk-image]][snyk-url]\n\nOverview\n--------\n\nNunjucks Intl uses [FormatJS][] components under the hood, the docs can be found on the webiste:\n\u003chttp://formatjs.io/\u003e\n\n### Features\n\n- Display numbers with separators.\n- Display dates and times correctly.\n- Display dates relative to \"now\".\n- Pluralize labels in strings.\n- Support for 200+ languages.\n- Runs in the browser and Node.js.\n- Built on standards.\n\n### Quick example\n\n```nunjucks\n{{ formatMessage(\n    intlGet(\"messages.post.meta\"),\n    {\n        num: post.comments.length,\n        ago: formatRelative(post.date)\n    })\n}}\n```\n\n```js\nvar data = {\n    post: {\n        date    : 1422046290531,\n        comments: [/*...*/]\n    }\n};\n\nvar intlData = {\n    locales : ['en-US'],\n    messages: {\n        post: {\n            meta: 'Posted {ago}, {num, plural, one{# comment} other{# comments}}'\n        }\n    }\n};\n\ndata.intl = intlData;\n\nvar html = nunjucks.renderString(/* Template source above */, data);\n```\n\nThis example would render: **\"Posted 3 days ago, 1,000 comments\"** to the `html` variable.\nThe `post.meta` message is written in the industry standard [ICU Message syntax][], which you can\nalso learn about on the [FormatJS website][FormatJS].\n\nIn all examples below, for simplicity, nunjucks.renderString is used, but, of course,\ntemplate render() works the same way.\n\n### API Methods\n\n#### Registering Nunjucks Intl with Nunjucks instance\n\nTo start using intl helpers in your template, first of all, you need to register helpers with your instance of\nNunjucks enviroment.\n\nThis is done by:\n\n```javascript\nconst nunjucks = require('nunjucks');\nconst env = nunjucks.configure();\n\nconst nunjucksIntl = require('nunjucks-intl');\n\nnunjucksIntl.registerWith(env);\n\n```\n\nThis adds a few global functions to nunjucks enviroment, so you can use them in your templates. Nunjucks Intl\nhelpers expect to find `intl` hash-map in template context data. More info below.\n\n#### intlGet helper\n\nThis helper implements a lookup process by path to access data from the intl object passed into the Nunjucks data\ncontext when rendering the template. Usually this helper is used in a subexpressions to lookup\ntranslated string messages;\n\n```javascript\nNunjucks.renderString('{{ formatMessage(intlGet(\"MSG\"), { firstName: firstName, lastName: lastName }) }}',\n    {\n        firstName: 'Vasiliy',\n        lastName : 'Pupkin',\n        intl: {\n            MSG : 'Hi, my name is {firstName} {lastName}.',\n            locales: 'en-US'\n        }\n    })\n// output: Hi, my name is Vasiliy Pupkin.\n```\n\n#### formatNumber helper\n\nThis helper is used to format numbers, including currencies and percentages.\n\n```javascript\nNunjucks.renderString('{{ formatNumber(NUM)}}', { NUM: 4.004, intl: { locales: 'en-US' }})\n// output: 4.004\n\nNunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 4.004, intl: { locales: 'de-DE' }})\n// output: 4,004\n\nNunjucks.renderString('{{ formatNumber(NUM) }}', {  NUM: 40000, intl: { locales: 'en-US' }})\n// output: 40,000\n\nNunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 40000, intl: { locales: 'de-DE' }})\n// output: 40.000\n\nNunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 40000.004, intl: { locales: 'en-US' }})\n// output: 40,000.004\n\nNunjucks.renderString('{{ formatNumber(NUM) }}', { NUM: 40000.004, intl: { locales: 'de-DE' }})\n// output: 40.000,004\n\nNunjucks.renderString('{{ formatNumber(40000, { style: \"currency\", currency: \"USD\" }) }}', { intl: { locales: 'en-US' }})\n// output: $40,000.00\n\nNunjucks.renderString('{{ formatNumber(40000, { style: \"currency\", currency: \"EUR\", currencyDisplay: \"code\" }) }}', { intl: { locales: 'en-US' }})\n// output: EUR40,000.00\n\n// also it's possible to return a currency even when using a different locale\nNunjucks.renderString('{{ formatNumber(40000, { style: \"currency\", currency: CURRENCY }) }}', { CURRENCY: 'JPY', intl: { locales: 'de-DE' }})\n// output: 40.000 ¥\n\nNunjucks.renderString('{{ formatNumber(0.45, { style: \"percent\" }) }}', { intl: { locales: 'en-US' }})\n// output: 45%\n\n```\n\n#### formatDate/formatTime helpers\n\nThis helpers are used to format dates, including time. You can pass a date string or timestamp.\nformatDate and formatTime works the same way, and the only difference is the place for searching custom formats.\nformatDate search them in formats.date, and formatTime - in formats.time respectively.\nIn example below, custom format is used, read more on [FormatJS][] site.\n\n```javascript\nvar dateStr   = 'Thu Jan 23 2014 18:00:44 GMT-0500 (EST)';\nvar timeStamp = 1390518044403; //same as dateStr\nvar intlData = {\n    locales: 'en-US',\n    formats: {\n        date: {\n            short: {\n                day: \"numeric\",\n                month: \"numeric\",\n                year: \"numeric\"\n            }\n        },\n        usual: {\n            hour: \"numeric\",\n            minute: \"numeric\",\n            timeZone: \"UTC\"\n        }\n    }\n};\n\nNunjucks.renderString('{{ formatDate(\"' + dateStr + '\") }}', { intl: { locales: 'en-US' }});\n// output: 1/24/2014\n\n//The same output using custom format\nNunjucks.renderString('{{ formatDate(\"' + dateStr + '\", \"short\") }}', { intl: intlData });\n// output: 1/24/2014\n\n//timestamp is passed as a number\nNunjucks.renderString('{{ formatDate(' + timeStamp + ') }}', { intl: { locales: 'en-US' }});\n// output: 1/24/2014\n\nNunjucks.renderString('{{ formatDate(' + timeStamp + ', \"usual\") }}', { intl: intlData });\n// output: 11:00 PM\n\n```\n\n#### formatRelative helper\n\nThis helper is used to format relative date and time.\n\n```javascript\nvar tomorrow = new Date().getTime() + (24 * 60 * 60 * 1000);\n\nNunjucks.renderString('{{ formatRelative(date) }}', { date: tomorrow, intl: { locales: 'en-US' }});\n// output: tomorrow\n\nNunjucks.renderString('{{ formatRelative(date, { style: \"numeric\" }) }}', { date: tomorrow, intl: { locales: 'en-US' }})\n// output: in 1 day\n\n// also it's possible to set NOW\nNunjucks.renderString('{{ formatRelative(2000, { now: 1000 }) }}', { intl: { locales: 'en-US' }});\n// output: in 1 second\n\nNunjucks.renderString('{{ formatRelative(0, { now: 1000 }) }}', { intl: { locales: 'en-US' }});\n// output: 1 second ago\n```\n\n#### formatMessage/formatHTMLMessage helpers\n\nThis helpers are used to format internationalization messages, including dates, numbers, and pluralization cases.\nUsing formatHTMLMessage, you can pass messages with html entities, and they will not be escaped.\nUser data is always escaped.\n\n```javascript\nNunjucks.renderString('{{ formatMessage({ firstName: firstName, lastName: lastName, intlName: \"MSG\" }) }}',\n    {\n        firstName: 'Vasiliy',\n        lastName : 'Pupkin',\n        intl: {\n            MSG      : 'Hi, my name is {firstName} {lastName}.',\n            locales: 'en-US'\n        }\n    });\n// output: Hi, my name is Vasiliy Pupkin.\n\nNunjucks.renderString('{{ formatMessage(POP_MSG, { city: city, population: population, census_date: census_date, timeZone: timeZone }) }}',\n    {\n        POP_MSG    : '{city} has a population of {population, number, integer} as of {census_date, date, long}.',\n        city       : 'Atlanta',\n        population : 5475213,\n        census_date: (new Date('1/1/2010')).getTime(),\n        timeZone   : 'UTC',\n        intl: { locales: 'en-US' }\n    });\n// output: Atlanta has a population of 5,475,213 as of January 1, 2010.\n\nNunjucks.renderString('{{ formatMessage(BDAY_MSG, { year: year }) }}',\n    {\n        BDAY_MSG: 'This is my {year, selectordinal, one{#st} two{#nd} few{#rd} other{#th}} birthday.',\n        year    : 3,\n        intl: { locales: 'en-US' }\n    });\n// output: This is my 3rd birthday.\n\n\nNunjucks.renderString('{{ formatHTMLMessage(intlGet(\"MSG\"), { firstName: firstName, lastName: lastName }) }}',\n    {\n        firstName: '\u003cVasiliy\u003e',\n        lastName : '\u003cPupkin\u003e',\n        intl: {\n            MSG : 'Hi, my \u003cname\u003e is {firstName} {lastName}.',\n            locales: 'en-US'\n        }\n    });\n// output: Hi, my \u003cname\u003e is \u0026lt;Vasiliy\u0026gt; \u0026lt;Pupkin\u0026gt;.\n```\n\nAlso, you can lookup into [tests](tests/helpers.js) for more usage examples.\n\nContribute\n----------\n\nLet's make Nunjucks Intl and FormatJS better! If you're interested in helping, all contributions\nare welcome and appreciated. Nunjucks Intl is just one of many packages that make up the\n[FormatJS suite of packages][FormatJS GitHub], and you can contribute to any/all of them,\nincluding the [Format JS website][FormatJS] itself.\n\n\nLicense\n-------\n\nThis software is free to use under the BSD license.\nSee the [LICENSE file][LICENSE] for license text and copyright information.\n\n\n[Nunjucks]: http://mozilla.github.io/nunjucks\n[npm-url]: https://www.npmjs.com/package/nunjucks-intl\n[npm-image]: https://img.shields.io/npm/v/nunjucks-intl.svg?style=flat\n[gh-build-test-url]: https://github.com/KSDaemon/nunjucks-intl/actions/workflows/build-and-test.yml\n[gh-build-test-image]: https://github.com/KSDaemon/nunjucks-intl/actions/workflows/build-and-test.yml/badge.svg\n[coveralls-url]: https://coveralls.io/github/KSDaemon/nunjucks-intl\n[coveralls-image]: https://img.shields.io/coveralls/KSDaemon/nunjucks-intl/master.svg?style=flat\n[license-image]: https://img.shields.io/badge/license-BSD-blue.svg\n[license-url]: http://opensource.org/licenses/BSD-2-Clause\n[snyk-image]: https://snyk.io/test/github/KSDaemon/nunjucks-intl/badge.svg?targetFile=package.json\n[snyk-url]: https://snyk.io/test/github/KSDaemon/nunjucks-intl?targetFile=package.json\n[FormatJS]: http://formatjs.io/\n[FormatJS GitHub]: http://formatjs.io/github/\n[ICU Message syntax]: http://formatjs.io/guide/#messageformat-syntax\n[LICENSE]: https://github.com/KSDaemon/nunjucks-intl/blob/master/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksdaemon%2Fnunjucks-intl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fksdaemon%2Fnunjucks-intl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksdaemon%2Fnunjucks-intl/lists"}