@postalsys/gettext

> Note: This is a fork of alexanderwallin/node-gettext with additional enhancements and maintenance updates.

@postalsys/gettext is a JavaScript implementation of a substantial subset of GNU gettext, a powerful localization framework originally written in C. This library enables developers to internationalize their JavaScript applications by handling translations, plural forms, and contexts, closely mirroring the functionality of the original gettext.

If you're interested in parsing or compiling .mo/.po files for use with this library or elsewhere, consider using gettext-parser.

Table of Contents

- Features
- Differences from GNU gettext
- Installation
- Usage
- Basic Example
- Error Events
- Recipes
- Loading Translations from .mo or .po Files
- API Reference
- Contributing
- License
- See Also

Features

- Comprehensive Localization Support: Handles domains, contexts, plurals, and more.
- File Format Compatibility: Supports .json, .mo, and .po files via gettext-parser.
- Extensive Language Support: Includes plural forms for 136 languages.
- Dynamic Configuration: Allows changing locale or domain at runtime.
- Debugging Tools: Provides detailed error messages when the debug option is enabled.
- Event Emission: Emits events for internal errors, such as missing translations.

$3

While @postalsys/gettext aims to closely emulate GNU gettext, there are notable differences:

1. No Category Support: Unlike GNU gettext, which supports categories like LC_MESSAGES, LC_NUMERIC, and LC_MONETARY, this library focuses solely on message localization, effectively always operating under the LC_MESSAGES category. For number formatting, currencies, dates, and other localization needs, consider using dedicated JavaScript libraries.
2. Manual Translation Loading: GNU gettext automatically reads translation files from the filesystem based on locale and category settings. In contrast, @postalsys/gettext requires developers to manually load and provide translations, accommodating both server-side and client-side environments.

Installation

Install the package via npm:

``sh
npm install @postalsys/gettext
`

Usage

$3

`js
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');

console.log(gt.gettext('The world is a funny place'));
// Output: "Världen är en underlig plats"
`

$3

@postalsys/gettext emits an error event when it encounters issues such as missing translations. You can handle these events as follows:

`js
// Set up your Gettext instance and add translations...

gt.on('error', error => {
console.error('Translation error:', error.message);
});

gt.gettext('An unrecognized message');
// Logs: 'Translation error: No translation found for msgid "An unrecognized message"'
`

$3

#### Loading Translations from .mo or .po Files

@postalsys/gettext works seamlessly with translations parsed by gettext-parser. Here's how you can load translations from .po files:

`js
const fs = require('fs');
const path = require('path');
const Gettext = require('@postalsys/gettext');
const { po } = require('gettext-parser');

// Directory where your translations are stored
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);
});

gt.setLocale('sv-SE');
console.log(gt.gettext('Hello'));
// Outputs the translated string in Swedish
`

API Reference

Gettext

* Gettext
* [new Gettext([options])](#new_Gettext_new)
* .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

$3

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

$3

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

$3

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

$3

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

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


$3

- locale: String - A locale

Example
`js
gt.setLocale('sv-SE')
`


$3

- domain: String - A gettext domain name

Example
`js
gt.setTextDomain('domainname')
`


$3

- msgid: String - String to be translated

Example
`js
gt.gettext('Some text')
`


$3

- domain: String - A gettext domain name
- msgid: String - String to be translated

Example
`js
gt.dgettext('domainname', 'Some text')
`


$3

- 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
`js
gt.ngettext('One thing', 'Many things', numberOfThings)
`


$3

- 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
`js
gt.dngettext('domainname', 'One thing', 'Many things', numberOfThings)
`


$3

- msgctxt: String - Translation context
- msgid: String - String to be translated

Example
`js
gt.pgettext('sports', 'Back')
`


$3

- domain: String - A gettext domain name
- msgctxt: String - Translation context
- msgid: String - String to be translated

Example
`js
gt.dpgettext('domainname', 'sports', 'Back')
`


$3

- 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
`js
gt.npgettext('sports', 'Back', '%d backs', numberOfBacks)
`


$3

- 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
`js
gt.dnpgettext('domainname', 'sports', 'Back', '%d backs', numberOfBacks)
`

License

This project is licensed under the MIT License. See the LICENSE file for details.

See Also

- gettext-parser - Parse and compile gettext translations between .po/.mo` files and JSON.
- lioness - Gettext library for React applications.
- react-gettext-parser - Extract translatable strings from React components.
- narp - CLI tool for synchronizing translations between your app and Transifex.