node-gettext is a JavaScript implementation of gettext.
If you just want to parse or compile mo/po files, check out gettext-parser.
NOTE: This is the README for v2 of node-gettext, which introduces many braking changes. v2 is currently in alpha. You can find the README for v1 here.
- 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
debugoption - Emits events for internal errors, such as missing translations
npm install --save node-gettextimport Gettext from 'node-gettext'
import swedishTranslations from './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'## Migrating from 1.x to 2.x
Version 1.x of node-gettext confused domains with locales, which version 2 has corrected. This contains the following breaking changes:
textdomain(domain)is nowsetLocale(locale)dgettext,dngettext,dpgettextanddnpgettextdoes not treat the leadingdomainargument as a locale, but as a domain. To get a translation from a certain locale you need to callsetLocale(locale)beforehand.- A new
setTextDomain(domain)has been introduced
On top of that there a couple of more breaking changes to be aware of:
addTextdomain(domain, file)is nowaddTranslations(locale, domain, translations)addTranslations(locale, domain, translations)only accepts a JSON object with the shape described in thegettext-parserREADME. To load translations from .mo or .po files, use gettext-parser._currentDomainis nowdomaindomainsis nowcatalogs- The instance method
__normalizeDomain(domain)has been replaced by a static methodGettext.getLanguageCode(locale)
Creates and returns a new Gettext instance.
Returns: Object - A Gettext instance
Params
options:Object- A set of options.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
Emits an event to all registered event listener.
Params
eventName:String- An event nameeventData:any- Data to pass to event listeners
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.
8000
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)Retrieves comments object for a translation. The comments object
has the shape { translator, extracted, reference, flag, previous }.
Returns: Object - Comments object or false if not found
Params
domain:String- A gettext domain namemsgctxt:String- Translation contextmsgid:String- String to be translated
Example
const comment = gt.getComment('domainname', 'sports', 'Backs')Deprecated
This function will be removed in the final 2.0.0 release.
Deprecated
This function will be removed in the final 2.0.0 release.
Returns the language code part of a locale
Returns: String - A language code
Params
locale:String- A case-insensitive locale string
Example
Gettext.getLanguageCode('sv-SE')
// -> "sv"MIT
- gettext-parser - Parsing and compiling gettext translations between .po/.mo files and JSON
- react-gettext-parser - Extracting gettext translatable strings from JS(X) code
- narp - Workflow CLI tool that syncs translations between your app and Transifex