Revision 703861 of L10n.formatValue

<p>{{ non-standard_header() }}</p>
<p>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 (etc. date/time formatting) and in all other UI related cases should be replaced with DOM attributes setting or {{ domxref("L10n.setAttributes()") }}.</p>
<p>As opposed to its synchronous counterpart, {{ domxref("L10n.get()") }}, <code>formatValue</code> internally waits for all the localization resources to be fetched.&nbsp; This makes it race condition-proof.</p>
<p><strong><span class="seoSummary"><code>formatValue</code> 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. </span></strong></p>
<p>Translations may use the double brace syntax (<code>\{{ placeable }}</code>) 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 <code>formatValue</code> and must be strings or numbers. If a variable fails to resolve, the final translation will contain the raw <code>\{{ placeable }}</code> syntax.</p>
<p>When no translation is found, or, in rare cases, when the translation contains unrecoverable errors (e.g. a cyclic reference in a placeable), <code>formatValue</code> will return the identifier that was requested.&nbsp; This behavior allows the developers to safely assume that the return value is always a string.</p>
<h2 id="Syntax">Syntax</h2>
<pre>
var translationPromise = navigator.mozL10n.formatValue(<em>identifier[</em>, <em>data]</em>);</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
 <dt>
  <code>identifier</code></dt>
 <dd>
  The string identifier of the translation to be retrieved.</dd>
 <dt>
  <code>data</code></dt>
 <dd>
  An object with variables to be interpolated into the translation. All members' values must be strings or numbers.</dd>
</dl>
<h3 id="Returns">Returns</h3>
<p>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.</p>
<h2 id="Example">Example</h2>
<dl>
 <dt>
  dialer.en-US.properties:</dt>
</dl>
<dl>
 <dd>
  <pre>
from-contact = Missed call from \{{ contact }}</pre>
 </dd>
</dl>
<dl>
 <dt>
  dialer.js:</dt>
</dl>
<dl>
 <dd>
  <pre class="brush: js">
navigator.mozL10n.formatValue('from-contact', {contact: primaryInfo.toString()}).then(function(value) {
  window.alert('The translation is ' + value);
});
</pre>
 </dd>
</dl>
<h2 id="Specification" name="Specification">Retrieving many translations at once</h2>
<p>Sometimes you may need to retrieve multiple translations at once.&nbsp; <code>formatValue</code> plays nicely with <code>Promise.all</code>.</p>
<pre>
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);
</pre>
<p>When you need to pass arguments into translations you can use</p>
<pre>
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);</pre>
<h2 id="Specification" name="Specification">Specification</h2>
<p>Not part of any specification.</p>
<h2 id="See_also">See also</h2>
<ul>
 <li>{{domxref("L10n")}}</li>
</ul>
<section id="Quick_Links">
 <ol>
  <li data-closed="" data-default-state="open"><strong><a href="#">Guides</a></strong>
   <ol>
    <li><a href="/en-US/Apps/Build/Localization">Localization</a></li>
   </ol>
  </li>
  <li data-closed="" data-default-state="open"><strong><a href="#">Properties</a></strong>
   <ol>
    <li>{{ domxref("L10n.language.code") }}</li>
    <li>{{ domxref("L10n.language.direction") }}</li>
    <li>{{ domxref("L10n.readyState") }}</li>
   </ol>
  </li>
  <li data-closed="" data-default-state="open"><strong><a href="#">Methods</a></strong>
   <ol>
    <li>{{ domxref("L10n.get") }}</li>
    <li>{{ domxref("L10n.formatValue") }}</li>
    <li>{{ domxref("L10n.ready") }}</li>
    <li>{{ domxref("L10n.once") }}</li>
   </ol>
  </li>
 </ol>
</section>