Staś Małolepszy

L20n 1.0 Release Candidate now available

The release candidate of L20n 1.0 allows safe HTML in translations and is the last call for reporting blocker bugs.

L20n 1.0 RC is now available for testing. We ask users of this release candidate to watch for and report any major bugs they encounter; if no release-blocking bugs are reported, L20n 1.0 will be released in approximately one week.

Following previous beta releases, this release adds the last big feature planned in the 1.0 scope: secure HTML localization which allows localizers to use some HTML in translations. Furthermore, two Context methods, ctx.get and ctx.getEntity, have been renamed to ctx.getSync and ctx.getEntitySync respectively.

You can download the RC from (which also received an overhaul) or from the builds repository. To quickly get started, clone the demo repository, which contains an example HTML file localized with L20n (preview).

Changes since Beta 4

Following is a summary of the most notable changes since Beta 4. You can also consult the full changelog:

  • ctx.get is now ctx.getSync,
  • ctx.getEntity is now ctx.getEntitySync,
  • a subset of HTML is now allowed in translations; the
    data-l10n-overlay attribute is now obsolete,
  • the maybeComplex optimization has been removed from strings,
  • all expressions are now compiled lazily, improving performance,
  • L20n now uses Grunt to automate the build tasks,
  • L20n successfully passed the security review.

HTML localization

Secure HTML localization was one of the last big features on our 1.0 list. In Beta 4 and before, the developer could add the (now obsolete) data-l10n-overlay attribute to any HTML element to allow translations to have HTML content. The RC removes this attribute completely and allows a subset of HTML elements to be present in all translations, without any intervention from the developer.

In particular, text-level semantic elements like em and strong are now allowed in all translations, together with certain translatable attributes, like title and placeholder. This allows localizers to stay in control when it comes to deciding where to use some HTML to mark up the text (for instance, they can freely use the sup element in Mme). Similarly, HTML entities are also allowed and available at localizer's discretion (e.g.  ).

The documentation gives a few other examples demonstrating how the HTML in the translation is sanitized before it's inserted into the DOM. You may also be interested in learning the details of the implementation from the original thread on the mailing list, as well as from bug 921169 and bug 922576.

getSync and getEntitySync

We also take this opportunity to rename two methods available on Context instances. ctx.get is now ctx.getSync and can be used, as before, to synchronously get a translation string from the Context instance. ctx.getEntity becomes ctx.getEntitySync and can be used, also as before, to synchronously get a translation object consisting of the string value, attributes and the language code.

Nothing has changed in the behavior of these methods (they already were synchronous before), and the change to their names is cosmetic and keeps L20n forward-compatible. It allows us to focus more on our asynchronous API, which in turn makes it possible to continue our research into language packages for L20n and into running L20n (or parts of it) in worker threads.

In L20n 1.0, ctx.getSync doesn't have a direct asynchronous counterpart (bug 931707). Instead, we encourage everyone to use the ctx.localize API, which is asynchronous and supports retranslation when the language changes and when values of L20n's globals change (the concept known as responsive localization). Here's an example:

ctx.localize(['hello', 'about'], function(l10n) {
  var node = document.querySelector('[data-l10n-id=hello]');
  node.textContent = l10n.entities.hello.value;

The callback function will be invoked when the translations of hello and about are available. It will also be called again if the user changes the language, or when the values of L20n's globals like @screen change (but only if hello or about actually use them).

Testing the RC

If you take the Release Candidate for a spin (download from or clone the demo repository), please report any bugs that you find (or things that look like bugs). Pending any new release-blocking bugs, we will release 1.0 final in approximately one week.

You can file bugs in Bugzilla, or find us in #l20n on, or email the tools-l10n mailing list. Thank you!

Published on 07.11.2013

Staś Małolepszy

Thoughts about the Internet, the information society, Mozilla and human-computer interactions.

Latest notes