Localizing strings in JavaScript

by 2 contributors:

The tutorial on getting started with localization explains how to localize strings that appear in your app's HTML. But many web apps don't just present a static interface: they construct elements of the interface dynamically using JavaScript. To localize an app like this you need to know how to retrieve the correct localized string in JavaScript, and that's the topic of this tutorial.

This guide is in four parts:

Before you start, you need to have performed the steps described in the setup article. That is, you need to have added:

  • the translations in properties files, one for each language
  • a locales.ini declaring which languages your app supports
  • the l10n.js library

l10n.js API

The l10n.js library adds an object to document called webl10n that provides the following functions:

  • get
  • getLanguage
  • setLanguage
  • getDirection

get()

Get the translation of a string in the current language. The argument to get() is the name side of a name=value line in the app.properties file:

document.webL10n.get("winter-is-coming"); // "Winter is coming"

You can pass arguments to this function to supply placeholders or to retrieve a specific plural form.

getLanguage()

Get the ISO-639-1 code of the current locale:

document.webl10n.getLanguage(); // "en-GB"

setLanguage()

Set the device language:

document.webl10n.setLanguage("en-GB");

getDirection()

Gets the direction ("ltr", "rtl") of thr current device language:

document.webl10n.getDirection(); // "ltr"

Placeholders

The article on setting up describes how localized strings can be made to contain placeholders: that is, strings passed in at runtime that should not be localized. For example, suppose the localized string is intended to greet the user:  "Hello, Bob!". The app.properties files might look like this:

// en/app.properties
greeting=Hello {{person}}!
// fr/app.properties
greeting=Bonjour {{person}} !

JavaScript code can then pass these placeholders into webl10n.get() as properties of a JSON object:

var user = "Bob";
var greeting = window.document.webL10n.get("greeting", {"person" : user});
// -> "Hello Bob!" if device language is en
// -> "Bonjour Bob !" if device language is fr

Plurals

The article on setting up describes how a translator can handle pluralization by supplying different forms of a string. For example:

tomatoCount={[ plural(n) ]}
tomatoCount[zero]=Vous n'avez pas de tomates :(.
tomatoCount[one]=Vous avez une tomate.
tomatoCount[other] = Vouz avez {{n}} tomates.

This file will return different values for tomatoCount depending on the value passed in as n:

var n = 1;
window.document.webL10n.get("tomatoCount", {"n" : count.value});
// -> "Vous avez une tomate." 

Example

We've provided a simple example showing how to localize strings in JavaScript. You can clone or download it from GitHub.

Document Tags and Contributors

Contributors to this page: necrophcodr, wbamberg
Last updated by: necrophcodr,