Welcome to gettext.js’s documentation!

gettext.js provides a GNU gettext like interface for use in browsers, a MO file to JS transpiler and a webpack loader for MO files.

Installation

Installation

yarn add gettextjs

Usage

Workflow

  1. Create your po files using your current workflow.
  2. Create your mo files using your current workflow.
  3. Choose one of the following:
    1. Transpile your mo files to js files using gettextjs
    2. Import your mo files in js and use the webpack loader.

Transpile using CLI

Transpile all your MO files to JS using gettextjs <input> <output>.

Note that the resulting code is ES7 code (including import) and needs to be transpiled before used.

Webpack

Add the gettextjs/dist/loader loader to your webpack config for mo files:

The babel-loader is needed because the gettextjs loader outputs ES7, but you can use another loader to do the JS->JS transpilation.

Using transpiled files

The transpiled files have a default export which is an instance of Translations(). They can either be used directly or you can call set_catalog() with the instance.

gettext() and ngettext() are equivalent to gettext(3) and ngettext(3). gettext() takes a single msgid and returns the translation for it, if it finds one, or the msgid. ngettext() is used for translations which may have plurals.

Reference

class Translations(headers, messages, plural)
Arguments:
  • string> headers (Immutable.Map<string,) – MO headers.
  • Immutable.List<string>> messages (Immutable.Map<string,) – The translations.
  • => number plural ((number)) – Function to resolve plural forms.

Usually this class should not be created manually.

Translations.gettext(msgid)
Arguments:
  • msgid (string) – Message ID to look up.
Returns:

Translated string (or input string if not found).
Translations.ngettext(msgid, msgid_plural, count)
Arguments:
  • msgid (string) – Message ID for the singular string.
  • msgid_plural (string) – Message ID for the plural string.
  • count (number) – Used to detect whether plural or singular form should be used.
Returns:

Translated string (or one of the input strings if not found).
set_catalog(catalog)
Arguments:
  • catalog (Gettext) –

Set a translation as the currently active, global translations.

gettext(msgid)
Arguments:
  • msgid (string) – Message ID to look up.
Returns:

Translated string (or input string if not found).

Uses the translations set by set_catalog() to translate a message ID.

ngettext(msgid, msgid_plural, count)
Arguments:
  • msgid (string) – Message ID for the singular string.
  • msgid_plural (string) – Message ID for the plural string.
  • count (number) – Used to detect whether plural or singular form should be used.
Returns:

Translated string (or one of the input strings if not found).

Uses the translations set by set_catalog() to translate a message ID.

Changelog

2.0.0

Release data: January 26, 2018

  • Re-wrote the whole library.
  • Ported MO->JS transpiler to Javascript.
  • Added webpack loader to load MO files directly in you sources.
  • Removed dependency on eval and new Function.
  • Renamed gettext.Gettext to gettext.Translations.

1.2

Release date: January 20, 2017

  • Removed eval from Javascript runtime.
  • Use yarn for development Javascript dependencies.

1.1

Release date: September 24, 2016

  • Made the JavaScript runtime an NPM package.
  • Removed the Gettext.load API. If you want to load catalogs via AJAX, please use the AJAX libary of your choice.
  • Added “global” APIs set_catalog(), gettext() and ngettext().
  • Removed docopt as a dependency for the compiler. The compiler now only depends on Python 3.5.

1.0

Release date: Dec 25, 2015

  • Initial release.

Indices and tables