L10n.formatValue

An asynchronous method returning a Promise used for retrieving localization strings from app's resources. This function should be used only when direct manipulation on the strings is needed (e.g., date/time formatting) and in all other UI related cases should be replaced with DOM attributes setting or L10n.setAttributes().

As opposed to its synchronous counterpart, L10n.get(), formatValue internally waits for all the localization resources to be fetched.  This makes it race condition-proof.

formatValue is used to retrieve translations from the localization resources, optionally interpolating them with additional variable data. If the translation is not found in the first supported locale, the L10n context will try the next locale in the fallback chain (asynchronously) until it finds an available translation.

Translations may use the double brace syntax ({{ placeable }}) to introduce variables that will be resolved on runtime and interpolated into the final string return value. The variable values must be specified in the second argument to formatValue and must be strings or numbers. If a variable fails to resolve, the final translation will contain the raw {{ placeable }} syntax.

When no translation is found, or, in rare cases, when the translation contains unrecoverable errors (e.g., a cyclic reference in a placeable), formatValue will return the identifier that was requested. This behavior allows the developers to safely assume that the return value is always a string.

Syntax

var translationPromise = navigator.mozL10n.formatValue(identifier[, data]);

Parameters

identifier

The string identifier of the translation to be retrieved.

data

An object with variables to be interpolated into the translation. All members' values must be strings or numbers.

Returns

A Promise which resolves to the translated string (in one of the supported locales) or the requested identifier if the translation was not found or contained errors.

Example

dialer.en-US.properties:

from-contact = Missed call from {{ contact }}

dialer.js:

navigator.mozL10n.formatValue('from-contact', {contact: primaryInfo.toString()}).then(function(value) {
  window.alert('The translation is ' + value);
});

Retrieving many translations at once

Sometimes you may need to retrieve multiple translations at once. formatValue plays nicely with Promise.all.

var stringIdentifiers = ['title', 'body', 'cancel', 'ok'];
function buildModal(strings) {
  //  strings[0] is the 'title' translation
}
Promise.all(
  stringIdentifiers.map(
    navigator.mozL10n.formatValue.bind(navigator.mozL10n))).then(
      buildModal);

When you need to pass arguments into translations you can use:

var stringIdentifiers = [
  ['title', { name: App.name }], ['body'], ['cancel'], ['ok']];
function buildModal(strings) {
  //  strings[0] is the 'title' translation with 
  // App.name interpolated inplace of {{ name }}
}
Promise.all(
  stringIdentifiers.map(
    Function.prototype.apply.bind(
      navigator.mozL10n.formatValue, navigator.mozL10n))).then(
        buildModal);

Specification

Not part of any specification.

See also

• L10n