Skip to content


Subversion checkout URL

You can clone with
Download ZIP
114 lines (79 sloc) 3.03 KB

The HTML Bindings

You can take advantage of HTML bindings to localize your HTML documents with L20n.


Production builds of L20n are available in the dist directory on release branches (v1.0.x, v2.x, v3.x). Major versions differ in API and are not backwards-compatible. Please use v3.x if you can.

You can also use bower to install L20n:

bower install l20n#v3.x

The dist/ directory contains subdirectories with different variations of L20n (called runtimes). The compat directory is ES5-compatible. The bundle variants are written in ES2015. For best cross-browser results use dist/compat/web/l20n.js.

Finally, include L20n in your HTML. It's recommended to include the l20n.js file as the first deferred script in the head element.

  <script defer src="dist/compat/web/l20n.js"></script>

Configure Languages

In order to know which language to display to the user, L20n needs the information about the languages your app is available in, as well as the default language.

<meta name="defaultLanguage" content="en-US">
<meta name="availableLanguages" content="de, en-US, fr, pl">

Optional: If you're also providing user-installable language packages via L20n, specify the app version:

<meta name="appVersion" content="2.5">

Add Resources

L20n.js supports three kinds of translation resources:

Include them in the <head> of your HTML:

<link rel="localization" href="locales/myApp.{locale}.l20n">
<link rel="localization" href="locales/myApp.{locale}.properties">
<link rel="localization" href="locales/myApp.{locale}.json">

Making HTML Elements Localizable

Use the data-l10n-id attribute on a node to mark it as localizable.

<p data-l10n-id="about"></p>

Notice that you don't have to put the text content in the HTML anymore (you still can if you want to). All content lives in the localization resources.

Use the data-l10n-args attribute to pass additional data into translations which will be interpolated via the {{ }} syntax. The data should be serialized JSON.

<h1 data-l10n-id="hello" data-l10n-args='{"username": "Mary"}'></h1>

Given the following translation:

<hello "Hello, {{ $username }}!">

…the result will be as follows (data- attributes omitted for clarity):

<h1>Hello, Mary!</h1>

The first time all DOM nodes are localized, the document.l10n.ready promise will resolve. On every following re-translation due to languages change, the document will fire a DOMRetranslated event.

Jump to Line
Something went wrong with that request. Please try again.