I18N.md

<!-- This Source Code Form is subject to the terms of the Mozilla Public
   - License, v. 2.0. If a copy of the MPL was not distributed with this
   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->

# 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