j29n

j29n (short for JavaScript Internationalization) is a simple and lightweight GNU gettext implementation for JavaScript. It makes it easy to load translations from PO or MO files and use them for localization in both browser and Node.JS. The library supports different translation domains, contexts and plural forms. Additionally, it comes with an built-in string formatting mechanism for parameterized messages.

j29n was inspired by Pomo.

Installation

j29n is published on npmjs and can be installed using npm.

npm install j29n

Browser Bundles

For the use in the browser, the source files have to be bundled together with their dependencies first. This bundled file and a minimized version were shipped with each NPM release and can be found in the dist directory. Additionally, the files are attatched to the respective GitHub releases. Alternatively, grunt can be used to build them from source manually by executing grunt browser.

j29n supports AMD module loading, so RequireJS can be used. Alternatively, the library can simply be embedded in an HTML page using the script tag. In this case, the j29n module will be made globally available.

Usage

The j29n module exports a j29n object, which is a singleton responsible for all the internationalization work and the only point of contact with the library.

Loading translation files

Load translations from string

j29n.load({
  mode: 'string',
  data: '\
        #: path/to/file.js:42 \
        msgctxt "Optional Context" \
        msgid "Original string" \
        msgstr "Translation"', //the literal PO contents
  domain: 'messages', // optional
});

Load translations by AJAX request (Browser-only)

j29n.load({
  mode: 'ajax',
  url: 'url/to/file.mo',
  type: 'application/gettext-mo', // or 'application/gettext-po' for PO files
  domain: 'messages' // optional
  ready: function() {
    // Optional callback is executed, when loading has finished successfully
  }
});

Translations can alternatively be loaded by AJAX request using the html link tag as shown in the following example:

<link href="/url/to/file.mo" type="application/gettext-mo" data-domain="optional domain" />
<script type="text/javascript">
  j29n.load({
    mode: 'link',
    ready: function() {
      // Optional callback is executed, when loading has finished successfully
    }
  });
</script>

Load translations from file system (Node-only)

j29n.load({
  mode: 'file',
  path: '/path/to/file.mo',
  domain: 'messages' // optional
  ready: function() {
    // Optional callback is executed, when loading has finished successfully
  }
});

Translate messages

j29n provides the following standard gettext functions for translating messages. For each of the functions, placeholderValues is an optional argument.

j29n.gettext(key, placeholderValues);
j29n.dgettext(domain, key, placeholderValues);
j29n.cgettext(context, key, placeholderValues);
j29n.dcgettext(domain, context, key, placeholderValues);
j29n.ngettext(singularKey, pluralKey, numericValue, placeholderValues);
j29n.dngettext(domain, singularKey, pluralKey, numericValue, placeholderValues);
j29n.cngettext(context, singularKey, pluralKey, numericValue, placeholderValues);
j29n.dcngettext(domain, context, singularKey, pluralKey, numericValue, placeholderValues);

Additionally, you can use the universal translate function, which calls the appropriate gettext function depending on the provided arguments. Please note, that cgettext and cngettext are not supported by translate.

j29n.translate(key, placeholderValues);

String formatting

Each of the functions above accepts an array of placeholder values for string formatting.

j29n.gettext('First three letters of the alphabet are %s, %s and %s.', ['a', 'b', 'c']);

Named placeholders are also supported. These placeholders refer to keys within an object you pass to the function.

j29n.gettext('First three letters of the alphabet are %(first)s, %(second)s and %(third)s.', {
  first: 'a',
  second: 'b'
  third: 'c'
});

For detailed documentation about string formatting (especially syntax of placeholders) have a look at sprintf.js, which is used internally.

Fuzzy translations

Per default, translations marked as fuzzy are ignored by the library. You can change the behavior using the setIgnoreFuzzy function:

j29n.setIgnoreFuzzy(false);

Testing

Jasmine is used as test framework for j29n. All features are tested using Node.JS only, so there is no need for browser testing so far. Tests are located in test/spec and can be executed using npm test.

License

This library is provided under MIT license.