var i18n = require('i18n-abide');

app.use(i18n.abide({
  supported_languages: ['en-US', 'de', 'es', 'db-LB', 'it-CH'],
  default_lang: 'en-US',
  debug_lang: 'it-CH',
  translation_directory: 'i18n'
}));

This block sets up the middleware and views with gettext support. We declare support for English, German, Spanish, and two debug locales (more on this later).

In your routes, you can use the gettext function in .js files.

exports.homepage = function(req, resp) {
  resp.render('home', {title: req.gettext("Hey, careful, man, there's a beverage here!")});
};

You can set locale in the scope of per-request instead of letting i18n-abide decide the locale for you. The following example shows how to set the locale of the request to zh_TW (Traditional Chinese):

exports.homepage = function(req, resp) {
  req.setLocale('zh_TW');
  resp.render('home', {title: "my title"});
};

In your layout files, you can add

<!DOCTYPE html>
<html lang="<%= lang %>" dir="<%= lang_dir %>">
  <head>
    <meta charset="utf-8">
    ...

In your templates files, you can use the gettext function in .ejs files:

<p><%= gettext("This will not stand, ya know, this aggression will not stand, man.") %></p>

i18n-abide also provides a format function for string interpolation.

These are both server side translations and client side translations. Server side works out of the box and is the most common use case.

If you also want to do client-side translations, i18n-abide provides lib/gettext.js and you can do the same in .js and .ejs files.

Setting Language via HTTP Header and URL

The i18n-abide module uses the accept-language HTTP header to determine which language to use. It is also possible to have language tags parsed on the URL with an option at setup:

app.use(i18n.abide({
  supported_languages: ['en-US', 'de', 'es', 'db-LB', 'it-CH'],
  default_lang: 'en-US',
  debug_lang: 'it-CH',
  translation_directory: 'i18n',
  locale_on_url: true
}));

Here the locale_on_url option has been set to true, which causes i18n-abide to perform an extra step with every request: each time a request comes to the server, the URL is examined for an optional language tag. Some examples include:

If a URL includes a language tag for one of the supported languages specified at setup, the request's accept-language header is overridden by the URL's language. The URL is then rewritten to no longer include this language tag, such that routes further down in the middleware chain are unaffected.

Given the URLs listed above, the following would happen in the i18n-abide middleware with locale_on_url set to true:

http://app.com/ --> http://app.com/
http://app.com/en-US/ --> locale is now en-US, url is http://app.com/
http://app.com/de --> locale is now de, url is http://app.com/

The locale_on_url option is off by default.

Translation files

The i18n-abide module can use either PO/POT files, which get transformed to JSON via provided command line tools, or PLIST (i.e., XML) files, which require no transformation prior to use.

By default PO/POT files are used. This can be changed during setup:

app.use(i18n.abide({
  supported_languages: ['en-US', 'de', 'es', 'db-LB', 'it-CH'],
  default_lang: 'en-US',
  debug_lang: 'it-CH',
  translation_directory: 'i18n',
  translation_type: 'plist'
}));

This will cause i18n-abide to look for files named messages.plist in locale directories beneath your translation_directory root. For example, the es language listed above should be located at i18n/es/messages.plist.

Working with PO/POT files, and gettext

If using the default of PO/POT files instead of plist, you must transform your strings such that i18n-abide can work with them.

Setup Gettext

$ mkdir -p locale/templates/LC_MESSAGES
$ ./node_modules/.bin/extract-pot --locale locale .

If you look in locale/templates/LC_MESSAGES/messages.pot you will see your strings have been extracted. Edit this file and make sure charset is set to UTF-8.

If there are certain files or directories you want to exclude, use --exclude one or more times. Example:

$ extract-pot --locale locale . --exclude tests --exclude examples

Example messages.pot:

"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: ./routes.js:81
msgid "Hey, careful, man, there's a beverage here!"
msgstr ""

#: views/404.ejs:5
msgid "This will not stand, ya know, this aggression will not stand, man."
msgstr ""

To create po files in bulk, do:

$ for l in en_US de es db_LB; do
    mkdir -p locale/${l}/LC_MESSAGES/
    msginit --input=./locale/templates/LC_MESSAGES/messages.pot \
            --output-file=./locale/${l}/LC_MESSAGES/messages.po \
            -l ${l}
  done

If you look at locale/en_US/LC_MESSAGES/messages.po, it will be very similar to your template messages.pot file.

This creates .po files which you can give to localizers to translate your copy.

Let's put the i18n-abide tools in our path:

$ export PATH=$PATH:node_modules/i18n-abide/bin

And run a string merge:

$ merge_po.sh ./locale

A merge takes strings from our .pot files and pushes them into our .po files. If you have podebug installed, it also automatically translates db-LB.

Debugging and Testing

db-LB is a special debug locale. To trigger it, set your Browser or Operating System language to Italian (Switzerland) which is it-CH. This fake locale db-LB will be triggered, it is David Bowie speak for the region of Labyrinth. Oh, hell ya a Dude / Bowie Mashup. That just happened.

Example: locale/db_LB/LC_MESSAGES/messages.po

"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#: routes.js:81
msgid "Hey, careful, man, there's a beverage here!"
msgstr "‮Hǝʎ´ ɔɐɹǝɟnʅ´ ɯɐu´ ʇɥǝɹǝ,s ɐ qǝʌǝɹɐƃǝ ɥǝɹǝ¡"

#: views/404.ejs:5
msgid "This will not stand, ya know, this aggression will not stand, man."
msgstr "‮⊥ɥıs ʍıʅʅ uoʇ sʇɐup´ ʎɐ ʞuoʍ´ ʇɥıs ɐƃƃɹǝssıou ʍıʅʅ uoʇ sʇɐup´ ɯɐu·"

And we will compile .po files into .mo files.

$ compile_mo.sh locale/

Now, start up your Node server and visit a page you've wrapped strings in Gettext...

See docs/USAGE.md for full details.

Keywords

FAQs

What is i18n-abide?

Is i18n-abide popular?

Is i18n-abide well maintained?

Package last updated on 11 Jul 2013

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install