gettext.js is a lightweight (3kB minified!) but complete and accurate GNU gettext port for Node.js and the browser. Manage your i18n translations the right way in your JavaScript projects.
Our aim is to port the famous GNU gettext and ngettext functions to JavaScript, Node.js and browser applications.
gettext.js should respect existing standards, and be lightweight, so:
- no dictionary loading management
- no extra features
The end-result is a tiny library (less than 200 lines of JavaScript) that implements the gettext() and ngettext() functions.
We have light JSON translation files: we only embed translated forms, and not much headers.
There are good i18n libraries, like Jed and i18n-next. But they are too complex and too heavy, or they do not fully embrace the gettext API and philosophy.
There's also the Orange-OpenSource/gettext.js package, which is pretty good, we were inspired by that project.
But that project has not been active since 2012 and doesn't have any tests.
apt-get install libjs-gettext.js- Install the library with this command:
npm install gettext.js --save - Require it in your project:
var i18n = require("gettext.js")(); i18n.gettext("foo");
For TypeScript definitions, use the third-party @types/gettext.js module.
Download the latest archive.
bower install gettext.js --save
<script src="/path/to/dist/gettext.iife.js" type="text/javascript"></script>
<script>
var i18n = window.i18n(options);
i18n.gettext("foo");
</script>As well as the IIFE (Immediately Invoked Function Expression) version, we also have releases for:
- CommonJS for Node.js
- AMD
- ESM
Instead of downloading gettext.js, you may use a npm CDN like unpkg or jsDelivr.
You can load your messages like this:
// i18n.setMessages(domain, locale, messages, plural_form);
i18n.setMessages(
"messages",
"fr",
{
Welcome: "Bienvenue",
"There is %1 apple": ["Il y a %1 pomme", "Il y a %1 pommes"],
},
"nplurals=2; plural=n>1;"
);Or:
// i18n.loadJSON(jsonData /*, domain */);
var json = {
"": {
language: "fr",
"plural-forms": "nplurals=2; plural=n>1;",
},
Welcome: "Bienvenue",
"There is %1 apple": ["Il y a %1 pomme", "Il y a %1 pommes"],
};
i18n.loadJSON(json, "messages");Read the Required JSON format section below for more info.
You can set your locale in the DOM, like this:
<html lang="fr"></html>Or use JavaScript:
i18n.setLocale("fr");| Name | Description | Shorthand |
|---|---|---|
gettext(msgid) |
Translate a string. | __() |
ngettext(msgid, msgid_plural, n) |
Translate a pluralizable string. | _n() |
pgettext(msgctxt, msgid) |
Translate a string specified by context. | _p() |
dcnpgettext(domain, msgctxt, msgid, msgid_plural, n) |
Translate a potentially pluralizable string, potentially specified by context, and potentially of a different domain (as specified in setMessages or loadJSON). |
None. |
ngettext and dcnpgettext accept a n parameter to specify the plural form.
i18n.ngettext('There is an apple', 'There are many apples', 1); // There is an apple
i18n.ngettext('There is an apple', 'There are many apples', 10); // There are many apples
i18n.ngettext('There is %1 apple', 'There are %1 apples', 10); // There are %1 apples
i18n.ngettext('There is %1 apple', 'There are %1 apples', 10, 10); // There are 10 applesAll four functions above can take extra arguments for variablization.
gettext('There are %1 in the %2', 'apples', 'bowl'); -> "There are apples in the bowl
ngettext('One %2', '%1 %2', 10, 10, 'bananas'); -> "10 bananas"
It uses the public method i18n.strfmt("string", var1, var2, ...) which you may re-use elsewhere in your project.
When you need to have literal percent sign followed by a number (common in Hebrew or Turkish) you can escape it using another percent sign, for example:
gettext('My credit card has an interest rate of %%%1', 20); -> "My credit card has an interest rate of %20"
Or without variables:
gettext('My credit card has an interest rate of %%20'); -> "My credit card has an interest rate of %20"
You'll find in /bin a po2json.js converter, based on the excellent po2json project that will dump your .po files into the proper JSON format below:
{
"": {
"language": "en",
"plural-forms": "nplurals=2; plural=(n!=1);"
},
"simple key": "It's translation",
"another with %1 parameter": "It's %1 translation",
"a key with plural": [
"a plural form",
"another plural form",
"could have up to 6 forms with some languages"
],
"a context\u0004a contextualized key": "translation here"
}Use bin/po2json.js input.po output.json or bin/po2json.js input.po output.json -p for pretty format.
You may use the xgettext-php parser to parse your files. It has helpful JavaScript and Handlebars parsers.
MIT
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
