node package manager

node-gettext

A JavaScript implementation of gettext, a localization framework

node-gettext

Build Status npm version

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

  • 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