Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

node-gettext

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

node-gettext

A JavaScript implementation of gettext, a localization framework

3.0.0
latest
Source
npm

Version published: 5 years ago

Weekly downloads: 148K; increased by17.25%

Maintainers: 2

Weekly downloads

Created: 13 years ago

What is node-gettext?

node-gettext is a JavaScript library that provides internationalization (i18n) and localization (l10n) functionalities. It allows developers to manage translations and localize their applications by using GNU gettext style .po and .mo files.

What are node-gettext's main functionalities?

Loading Translations

This feature allows you to load translation files into the node-gettext instance. The example demonstrates how to read a .po file and add it to the gettext instance under a specific domain.

const Gettext = require('node-gettext');
const fs = require('fs');
const gt = new Gettext();
const translations = fs.readFileSync('path/to/your/translation/file.po');
gt.addTextdomain('your_domain', translations);

Translating Strings

This feature allows you to translate strings using the loaded translations. The example shows how to translate the string 'Hello, world!' using the gettext instance.

const translatedString = gt.gettext('Hello, world!');
console.log(translatedString);

Setting Locale

This feature allows you to set the locale for translations. The example demonstrates how to set the locale to Spanish ('es') and then translate the string 'Hello, world!'.

gt.setLocale('es');
const translatedString = gt.gettext('Hello, world!');
console.log(translatedString);

Plural Forms

This feature allows you to handle plural forms in translations. The example shows how to translate singular and plural forms of a string based on the count.

const singular = gt.ngettext('%d apple', '%d apples', 1);
const plural = gt.ngettext('%d apple', '%d apples', 2);
console.log(singular);
console.log(plural);

Other packages similar to node-gettext

node-gettext

node-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.

NOTE: This is the README for v2 of node-gettext, which introduces several braking changes. 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

Differences from GNU gettext

There are two main differences between node-gettext and GNU's gettext:

There are no categories. GNU gettext features categories such as LC_MESSAGES, LC_NUMERIC and LC_MONETARY, but since there already is a plethora of great JavaScript libraries to deal with numbers, currencies, dates etc, node-gettext is simply targeted towards strings/phrases. You could say it just assumes the LC_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) and setlocale(category, locale), where these four parameters combined are used to read the appropriate translations file.

However, since node-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.

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'

Recipes

Load and add translations from .mo or .po files

node-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:

import fs from 'fs'
import path from 'path'
import Gettext from 'node-gettext'
import { po } from '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)
})

API

Gettext

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()
- ~~.addTextdomain()~~

new Gettext([options])

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.

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