A fork of alexanderwallin/node-gettext
@postalsys/gettext
is a JavaScript implementation of (a large subset of) gettext, a localization framework originally written in C.
If you just want to parse or compile mo/po files, for use with this library or elsewhere, check out gettext-parser.
- Supports domains, contexts and plurals
- Supports .json, .mo and .po files with the help of gettext-parser
- Ships with plural forms for 136 languages
- Change locale or domain on the fly
- Useful error messages enabled by a
debug
option - Emits events for internal errors, such as missing translations
There are two main differences between @postalsys/gettext
and GNU's gettext:
- There are no categories. GNU gettext features categories such as
LC_MESSAGES
,LC_NUMERIC
andLC_MONETARY
, but since there already is a plethora of great JavaScript libraries to deal with numbers, currencies, dates etc,@postalsys/gettext
is simply targeted towards strings/phrases. You could say it just assumes theLC_MESSAGES
category at all times. - You have to read translation files from the file system yourself. GNU gettext is a C library that reads files from the file system. This is done using
bindtextdomain(domain, localesDirPath)
andsetlocale(category, locale)
, where these four parameters combined are used to read the appropriate translations file.
However, since @postalsys/gettext
needs to work both on the server in web browsers (which usually is referred to as it being universal or isomorphic JavaScript), it is up to the developer to read translation files from disk or somehow provide it with translations as pure JavaScript objects using addTranslations(locale, domain, translations)
.
bindtextdomain
will be provided as an optional feature in a future release.
npm install --save @postalsys/gettext
const Gettext = require('@postalsys/gettext');
const swedishTranslations = require('./translations/sv-SE.json');
const gt = new Gettext();
gt.addTranslations('sv-SE', 'messages', swedishTranslations);
gt.setLocale('sv-SE');
gt.gettext('The world is a funny place');
// -> "Världen är en underlig plats"
// Add translations etc...
gt.on('error', error => console.log('oh nose', error));
gt.gettext('An unrecognized message');
// -> 'oh nose', 'An unrecognized message'
@postalsys/gettext
expects all translations to be in the format specified by gettext-parser
. Therefor, you should use that to parse .mo or .po files.
Here is an example where we read a bunch of translation files from disk and add them to our Gettext
instance:
const fs = require('fs');
const path = require('path');
const Gettext = require('@postalsys/gettext');
const { po } = require('gettext-parser');
// In this example, our translations are found at
// path/to/locales/LOCALE/DOMAIN.po
const translationsDir = 'path/to/locales';
const locales = ['en', 'fi-FI', 'sv-SE'];
const domain = 'messages';
const gt = new Gettext();
locales.forEach(locale => {
const fileName = `${domain}.po`;
const translationsFilePath = path.join(translationsDir, locale, fileName);
const translationsContent = fs.readFileSync(translationsFilePath);
const parsedTranslations = po.parse(translationsContent);
gt.addTranslations(locale, domain, parsedTranslations);
});
- Gettext
- new Gettext([options])
- .on(eventName, callback)
- .off(eventName, callback)
- .addTranslations(locale, domain, translations)
- .setLocale(locale)
- .setTextDomain(domain)
- .gettext(msgid) ⇒
String
- .dgettext(domain, msgid) ⇒
String
- .ngettext(msgid, msgidPlural, count) ⇒
String
- .dngettext(domain, msgid, msgidPlural, count) ⇒
String
- .pgettext(msgctxt, msgid) ⇒
String
- .dpgettext(domain, msgctxt, msgid) ⇒
String
- .npgettext(msgctxt, msgid, msgidPlural, count) ⇒
String
- .dnpgettext(domain, msgctxt, msgid, msgidPlural, count) ⇒
String
- .textdomain()
- .setlocale()
Creates and returns a new Gettext instance.
Returns: Object
- A Gettext instance
Params
[options]
:Object
- A set of options.sourceLocale
:String
- The locale that the source code and its texts are written in. Translations for this locale is not necessary..debug
:Boolean
- Whether to output debug info into the console.
Adds an event listener.
Params
eventName
:String
- An event namecallback
:function
- An event handler function
Removes an event listener.
Params
eventName
:String
- An event namecallback
:function
- A previously registered event handler function
Stores a set of translations in the set of gettext catalogs.
Params
locale
:String
- A locale stringdomain
:String
- A domain nametranslations
:Object
- An object of gettext-parser JSON shape
Example
gt.addTranslations('sv-SE', 'messages', translationsObject);
Sets the locale to get translated messages for.
Params
locale
:String
- A locale
Example
gt.setLocale('sv-SE');
Sets the default gettext domain.
Params
domain
:String
- A gettext domain name
Example
gt.setTextDomain('domainname');
Translates a string using the default textdomain
Returns: String
- Translation or the original string if no translation was found
Params
msgid
:String
- String to be translated
Example
gt.gettext('Some text');
Translates a string using a specific domain
Returns: String
- Translation or the original string if no translation was found
Params
domain
:String
- A gettext domain namemsgid
:String
- String to be translated
Example
gt.dgettext('domainname', 'Some text');
Translates a plural string using the default textdomain
Returns: String
- Translation or the original string if no translation was found
Params
msgid
:String
- String to be translated when count is not pluralmsgidPlural
:String
- String to be translated when count is pluralcount
:Number
- Number count for the plural
Example
gt.ngettext('One thing', 'Many things', numberOfThings);
Translates a plural string using a specific textdomain
Returns: String
- Translation or the original string if no translation was found
Params
domain
:String
- A gettext domain namemsgid
:String
- String to be translated when count is not pluralmsgidPlural
:String
- String to be translated when count is pluralcount
:Number
- Number count for the plural
Example
gt.dngettext('domainname', 'One thing', 'Many things', numberOfThings);
Translates a string from a specific context using the default textdomain
Returns: String
- Translation or the original string if no translation was found
Params
msgctxt
:String
- Translation contextmsgid
:String
- String to be translated
Example
gt.pgettext('sports', 'Back');
Translates a string from a specific context using s specific textdomain
Returns: String
- Translation or the original string if no translation was found
Params
domain
:String
- A gettext domain namemsgctxt
:String
- Translation contextmsgid
:String
- String to be translated
Example
gt.dpgettext('domainname', 'sports', 'Back');
Translates a plural string from a specific context using the default textdomain
Returns: String
- Translation or the original string if no translation was found
Params
msgctxt
:String
- Translation contextmsgid
:String
- String to be translated when count is not pluralmsgidPlural
:String
- String to be translated when count is pluralcount
:Number
- Number count for the plural
Example
gt.npgettext('sports', 'Back', '%d backs', numberOfBacks);
Translates a plural string from a specifi context using a specific textdomain
Returns: String
- Translation or the original string if no translation was found
Params
domain
:String
- A gettext domain namemsgctxt
:String
- Translation contextmsgid
:String
- String to be translatedmsgidPlural
:String
- If no translation was found, return this on count!=1count
:Number
- Number count for the plural
Example
gt.dnpgettext('domainname', 'sports', 'Back', '%d backs', numberOfBacks);
C-style alias for setTextDomain
C-style alias for setLocale
See: Gettext#setLocale
MIT
- gettext-parser - Parsing and compiling gettext translations between .po/.mo files and JSON
- lioness – Gettext library for React
- react-gettext-parser - Extracting gettext translatable strings from JS(X) code
- narp - Workflow CLI tool that syncs translations between your app and Transifex