L10n.js reference

This article provides a reference for the l10n.js library, and its associated date helper, l10n_date.js.

l10n.js reference

Most of the default Firefox OS apps use a <script> element similar to the following to load the L10n.js library:

<script defer src="/shared/js/l10n.js" charset="utf-8"></script>

To use this library in your own application, you will need to copy the l10n.js file to your local project and change the src attribute to suit.

Once loaded, the L10n.js library will expose a navigator.mozL10n object that can be used for client side localization.

Methods

The mozL10n object contains the following methods.

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"

setAttributes()

The pattern of setting l10n-id and l10n-args is so common that l10n.js provides a helper function to do this:

navigator.mozL10n.setAttributes(elem, 'label1', {'name': 'John'});

getAttributes()

In order to retrieve localization attributes, you can use the getAttributes helper:

var l10nAttrs = navigator.mozL10n.getAttributes(elem); // {id: 'label1', args: { 'name': 'John' }}

once()

The once method allows you to define a callback that fires when localization for the current document is complete.

var button1 = document.querySelector("#button1");
button1.setAttribute('data-l10n-id', 'label1');

navigator.mozL10n.once(function() {
  button1.style.display = 'block';
});

Because of the asynchronous nature of localization, the l10n-id may be set on the button before l10n resources are ready, in which case the localization will happen only once the resources are loaded.

once allows you to execute code only when localization is completed and resources are available.

It should guard any code that wants to use the get method, and code that displays localized UI.

Properties

The mozL10n object contains the following properties.

language

The language property contains a getter and setter for the language code. The language property also contains a getter for the language direction, for supporting right to left (Arabic or Hebrew)  and left to right languages.

var mycode = navigator.mozL10n.language.code;
navigator.mozL10n.language.code = "fr";
navigator.mozL10n.language.direction //returns rtl or ltr

l10n_date.js reference

For date and time manipulation, Gaia applications extend the capabilities of L10n.js with the l10n_date.js library. As with the l10n.js library, it implements some features that may not be compatible with all browsers. l10n_date.js is available in the Gaia source tree and uses the same property structure described in the L10n.js section of this article. Gaia apps that use this library all rely on a shared set of property files. The locale specific property files are located in the date directory. These property files define formats and strings for items like the day a week starts on, short date formats, and the names of months. To use this library in your own application, you will need to copy all of the files to your specific project.

<link rel="localization" href="locales/date.{locale}.properties" />
<script defer src="js/l10n_date.js"></script>

When using the l10n_date library’s formatting methods, the strings in the property files can use standard C++ date/time formatting codes. As an example of this, examine the Gaia Clock app’s property file. This file contains the following entry for dateFormat for the en-US locale.

dateFormat = %A, %B %e

Using the formatLocale method within the l10n_date library, this will return:

“Full Weekday Name” “Full Month Name” “Day of the Month” (Thursday January 29).

The French version of the property file defines the same key in the following fashion.

dateFormat = %A %e %B

This will produce:

“Full Weekday Name” “Day of the Month” “Full Month” (jeudi 25 janvier).

When you include the l10n_date library, a new method is available to the mozL10n object: navigator.mozL10n.DateTimeFormat(). Once instantiated, this object has several methods that can be used to localize dates.

localeFormat()

The localeFormat method takes a date object parameter and a format pattern parameter and returns the date formatted as specified in the pattern. This method should be used in conjunction with the L10N.js get method to format a localized date.

button3.onclick = function () {
    navigator.mozL10n.language.code = "fr";
    navigator.mozL10n.ready( function() {
        var d = new Date();
        var f = new navigator.mozL10n.DateTimeFormat();
        var format = navigator.mozL10n.get('dateFormat');
        var formatted = f.localeFormat(d, format);
        alert( formatted );
    });    
}

localeDateString(), localeTimeString(), and localeString()

These three methods are just variations on the localeFormat method that return formatted dates based on the following key values within the date properties files:

//en-US
//localeString returns
dateTimeFormat_%c = %a %b %e %Y %I:%M:%S %p
//localeDateString returns
dateTimeFormat_%x = %m/%d/%Y
//localeTimeString returns
dateTimeFormat_%X = %I:%M:%S %p

fromNow()

The fromNow method takes a date/time parameter and returns a locale-formatted string expressing the difference in time between the current date/time and the date/time passed in. The formatted string will be based on the strings defined in the date properties file. For example:

//Executed on 7/25/2013 12:11:00
var d = new Date("July 25, 2013 11:13:00");
var f = new navigator.mozL10n.DateTimeFormat();
alert( f.fromNow(d));

would alert “58 Minutes Ago” in the en-US locale. The string will be formatted using the minutes-ago-long key in the date properties file.

minutes-ago-long={[ plural(value) ]}
minutes-ago-long[zero] = just now
minutes-ago-long[one] = a minute ago
minutes-ago-long[two] = {{ value }} minutes ago
minutes-ago-long[few] = {{ value }} minutes ago
minutes-ago-long[many] = {{ value }} minutes ago
minutes-ago-long[other] = {{ value }} minutes ago