I18N.md

# i18n Support

Working with a localized version of BrowserID is totally optional for
casual development.

To get started, please [read the l10n locale doc](http://svn.mozilla.org/projects/l10n-misc/trunk/browserid/README).

## Development

Any copy, label, or error message that will be shown to users **should** be wrapped in a gettext function.

These strings must be evaluated in the scope of a request, so we know which locale the user has.

In JavaScript or EJS templates use `gettext` or `ngettext`. If you need to do string interpolation, use the
[format](../lib/i18n.js) function, which is kind of like node.js' util.format, except crappier.

Using `_` is more idiomatic, but conflicts with `underscore.js` on the client side JS and EJS files.

Technically, you can alias gettext to _ and use util.format, etc in node.js code... but for development consistency,
we should keep EJS templates looking similar, regardless of if they are evaluated client or server-side.

## Variables

The request object and the response's template context have the following variables:

 * lang - User's preferred language
 * lang_dir - rtl or ltr (BIDI language support)
 * locale - OS level locale code
 * gettext, ngettext - Gettext functions
 * format - for string interpolation

## Tools

``scripts/every_locale.js`` - will output a list of every locale under the locale directory. This can
be copied into ``config/l10n-all.json``.

``scripts/check_l10n_config.js`` - Run with the ``CONFIG_FILES`` environment variable set to the one json
config file which you'll like to validate. Examples:

    CONFIG_FILES=/home/ozten/Projects/browserid/config/l10n-prod.json node ./scripts/check_l10n_config.js
    CONFIG_FILES=/home/ozten/Projects/browserid/config/l10n-all.json node ./scripts/check_l10n_config.js

## Debugging

If code is evaluated in node.js (server-side) then node-gettext is providing the string
translation. Strings are from the messages.mo files under the locale directory. MO files
are binary, compiled from the PO files.

If code is evaluated on the client-side, then resources/static/shared/gettext.js is in
the house... strings are from resources/static/i18n JSON files.

If code is evaluated in your head, then clearly we are post-singularity. Why are you
still using gettext?

Use the eo locale for development and debugging. It is auto-translated with:
for catalog in messages client; do
  echo "Translating ${catalog}.po"
  podebug --rewrite=flipped -i locale/templates/LC_MESSAGES/${catalog}.pot -o locale/eo/LC_MESSAGES/${catalog}.po
done

## New Locales

To add a new language, and thus a new locale to BrowserID, do the following:
Assuming you want to add eo for Esperanto support...

    mkdir -p locale/eo/LC_MESSAGES

    msginit --input=./locale/templates/LC_MESSAGES/messages.pot \
            --output-file=./locale/eo/LC_MESSAGES/messages.po \
            -l eo

    msginit --input=./locale/templates/LC_MESSAGES/client.pot \
            --output-file=./locale/eo/LC_MESSAGES/client.po \
            -l eo