This article needs a technical review. How you can help.
Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.
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.