node-gettext

node-gettext

node-gettext is a JavaScript implementation of gettext, a localization framework.

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 and is currently in alpha. You can find the README for v1 here.

• Features
• Installation
• Usage
• Migrating from v1 to v2
• API
• License
• See also

Features

• 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

Installation

npm install --save node-gettext

Usage

import 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"

Error events

// Add translations etc...

gt.on('error', error => console.log('oh nose', error))
gt.gettext('An unrecognized message')
// -> 'oh nose', 'An unrecognized message'

## Migrating from v1 to v2

Version 1 of node-gettext confused domains with locales, which version 2 has corrected. node-gettext also no longer parses files or file paths for you, but accepts only ready-parsed JSON translation objects.

Here is a full list of all breaking changes:

• textdomain(domain) is now setLocale(locale)
• dgettext, dngettext, dpgettext and dnpgettext does not treat the leading domain argument as a locale, but as a domain. To get a translation from a certain locale you need to call setLocale(locale) beforehand.
• A new setTextDomain(domain) has been introduced
• addTextdomain(domain, file) is now addTranslations(locale, domain, translations)
• addTranslations(locale, domain, translations) only accepts a JSON object with the shape described in the gettext-parser README. To load translations from .mo or .po files, use gettext-parser, and it will provide you with valid JSON objects.
• _currentDomain is now domain
• domains is now catalogs
• The instance method __normalizeDomain(domain) has been replaced by a static method Gettext.getLanguageCode(locale)

API

Gettext

new Gettext(options)

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.

gettext.on(eventName, callback)

Adds an event listener.

Params

• eventName: String - An event name
• callback: function - An event handler function

gettext.off(eventName, callback)

Removes an event listener.

Params

• eventName: String - An event name
• callback: function - A previously registered event handler function

gettext.emit(eventName, eventData)

Emits an event to all registered event listener.

Params

• eventName: String - An event name
• eventData: any - Data to pass to event listeners

gettext.addTranslations(locale, domain, translations)

Stores a set of translations in the set of gettext catalogs.

Params

• locale: String - A locale string
• domain: String - A domain name
• translations: Object - An object of gettext-parser JSON shape

Example

gt.addTranslations('sv-SE', 'messages', translationsObject)

gettext.setLocale(locale)

Sets the locale to get translated messages for.

Params

• locale: String - A locale

Example

gt.setLocale('sv-SE')

gettext.setTextDomain(domain)

Sets the default gettext domain.

Params

• domain: String - A gettext domain name

Example

gt.setTextDomain('domainname')

gettext.gettext(msgid) ⇒ String

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')

gettext.dgettext(domain, msgid) ⇒ String

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 name
• msgid: String - String to be translated

Example

gt.dgettext('domainname', 'Some text')

gettext.ngettext(msgid, msgidPlural, count) ⇒ String

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 plural
• msgidPlural: String - String to be translated when count is plural
• count: Number - Number count for the plural

Example

gt.ngettext('One thing', 'Many things', numberOfThings)

gettext.dngettext(domain, msgid, msgidPlural, count) ⇒ String

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 name
• msgid: String - String to be translated when count is not plural
• msgidPlural: String - String to be translated when count is plural
• count: Number - Number count for the plural

Example

gt.dngettext('domainname', 'One thing', 'Many things', numberOfThings)

gettext.pgettext(msgctxt, msgid) ⇒ String

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 context
• msgid: String - String to be translated

Example

gt.pgettext('sports', 'Back')

gettext.dpgettext(domain, msgctxt, msgid) ⇒ String

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 name
• msgctxt: String - Translation context
• msgid: String - String to be translated

Example

gt.dpgettext('domainname', 'sports', 'Back')

gettext.npgettext(msgctxt, msgid, msgidPlural, count) ⇒ String

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 context
• msgid: String - String to be translated when count is not plural
• msgidPlural: String - String to be translated when count is plural
• count: Number - Number count for the plural

Example

gt.npgettext('sports', 'Back', '%d backs', numberOfBacks)

gettext.dnpgettext(domain, msgctxt, msgid, msgidPlural, count) ⇒ String

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 name
• msgctxt: String - Translation context
• msgid: String - String to be translated
• msgidPlural: String - If no translation was found, return this on count!=1
• count: Number - Number count for the plural

Example

gt.dnpgettext('domainname', 'sports', 'Back', '%d backs', numberOfBacks)

gettext.getComment(domain, msgctxt, msgid) ⇒ Object

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 name
• msgctxt: String - Translation context
• msgid: String - String to be translated

Example

const comment = gt.getComment('domainname', 'sports', 'Backs')

gettext.addTextdomain()

Deprecated

This function will be removed in the final 2.0.0 release.

gettext.textdomain()

Deprecated

This function will be removed in the final 2.0.0 release.

Gettext.getLanguageCode(locale) ⇒ String

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"

License

MIT

See also

• 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