L10n

Fireplace comes with a comprehensive set of tools to ensure proper localization of strings and interfaces.

Features and Usage

Translated string replacement

To mark a string as translatable, simple pass it to the gettext() function found in the l10n module.

var gettext = l10n.gettext;  // You must assign the `gettext()` function to a variable.
document.write(gettext('This is the translatable string!'));

NOTE: You MUST NOT call l10n.gettext() directly. It MUST be assigned to a variable and called in that manner. If this isn't done, the string extractor will not detect the call.

To translate strings in templates, use the _() function. This behaves exactly the same as gettext().

<div>{{ _('This is a translated string.') }}</div>

Pluralized translated string replacement

Pluralized strings are translated very similarly to singular strings. Instead of using gettext(), the ngettext() function is used. ngettext() accepts a third parameter for string formatting, and this object must contain a value n.

var ngettext = l10n.ngettext;  // You must assign the `gettext()` function to a variable.
document.write(
    ngettext('There is {n} translated string!',
             'There are {n} translated strings!',
             {n: Math.round(Math.random() * 3)})
);

NOTE: You MUST NOT call l10n.ngettext() directly for the same reason that l10n.gettext() cannot be called directly.

To pluralize strings in templates, use the _plural() function. This behaves exactly the same as ngettext(), except n can be passed as a keyword argument.

<div>{{ _plural('{n} string', '{n} strings', n=this.count) }}</div>

Formatted translated strings

gettext() and ngettext() (and _() and _plural()) accept an additional parameter which allows for string formatting. This can be specified as an object or via keyword arguments in a template.

var gettext = l10n.gettext;
document.write(gettext('I <3 {name}!', {name: "cvan"}));
// "I <3 cvan"

var ngettext = l10n.ngettext;
document.write(ngettext('{n} {type} string!', '{n} {type} strings!',
                        {n: 3, type: 'Basta'}));
// "3 Basta strings!"

<div>{{ _('{person} is the best', person='krupa') }}</div>
<div>{{ _plural('{person} scored {n} point', '{person} scored {n} points',
                n=this.points, person=this.player) }}</div>

RTL support

When the user is visiting the site with a language which reads right-to-left, the html-rtl class will be applied to the body. Otherwise, the html-ltr class will be applied to the body.

Extracting strings

commonplace extract_strings

The messages.pot file in locale/templates/LC_MESSAGES will be updated. This contains all of the project's localizable strings. Errors will be generated if any translation functions have been misused.

L10n comments

Comments may be left for localizers such that the comments are formatted as:

Nunjucks:
{# L10n: <message> #}
{{ _('foo') }}

JS previous line:
// L10n: <message>
gettext('foo');

JS same line:
gettext('foo');  // L10n: <message>

JS previous line block:
/* L10n: <message> */
gettext('foo');

Nunjucks L10n comments must always come before the string. JS comments may appear on the same line, though this must be lexical and not syntactical. For instance, the following will not work:

// BAD! Don't do this.
var foo = gettext(
    'foo'
); // L10n: 'foo' is a word.

Generating language packs

commonplace langpacks

The src/locales/ directory will be updated with the latest strings from the .po files in locale/.

Testing Locales

You can add a query parameter to the URL to force a language override:

http://localhost:8675/?lang=pt-BR