dom/webidl/DocumentL10n.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /**
   8  * An object used to carry localization information from and to an
   9  * Element.
  10  *
  11  * Fields:
  12  *    id - identifier of a message used to localize the element.
  13  *  args - an optional map of arguments used to format the message.
  14  *         The argument will be converted to/from JSON, so can
  15  *         handle any value that JSON can, but in practice, the API
  16  *         will only use a string or a number for now.
  17  */
  18 dictionary L10nKey {
  19   required DOMString id;
  20   object? args;
  21 };
  22
  23 /**
  24  * DocumentL10n is a public interface for handling DOM localization.
  25  *
  26  * In it's current form it exposes the DOMLocalization API which
  27  * allows for localization-specific DOM operations on a defined
  28  * localization context, and retrival of formatted localization
  29  * messages out of that context.
  30  *
  31  * The context is created when `<link rel="localization"/>` elements
  32  * are added to the document, and is removed in case all links
  33  * of that type are removed from it.
  34  */
  35 [NoInterfaceObject]
  36 interface DocumentL10n {
  37   /**
  38    * Formats a value of a localization message with a given id.
  39    * An optional dictionary of arguments can be passed to inform
  40    * the message formatting logic.
  41    *
  42    * Example:
  43    *    let value = await document.l10n.formatValue("unread-emails", {count: 5});
  44    *    assert.equal(value, "You have 5 unread emails");
  45    */
  46   [NewObject] Promise<DOMString> formatValue(DOMString aId, optional object aArgs);
  47
  48   /**
  49    * Formats values of a list of messages with given ids.
  50    *
  51    * Example:
  52    *    let values = await document.l10n.formatValues([
  53    *      {id: "hello-world"},
  54    *      {id: "unread-emails", args: {count: 5}
  55    *    ]);
  56    *    assert.deepEqual(values, [
  57    *      "Hello World",
  58    *      "You have 5 unread emails"
  59    *    ]);
  60    */
  61   [NewObject] Promise<sequence<DOMString>> formatValues(sequence<L10nKey> aKeys);
  62
  63   /**
  64    * Formats values and attributes of a list of messages with given ids.
  65    *
  66    * Example:
  67    *    let values = await document.l10n.formatMessages([
  68    *      {id: "hello-world"},
  69    *      {id: "unread-emails", args: {count: 5}
  70    *    ]);
  71    *    assert.deepEqual(values, [
  72    *      {
  73    *        value: "Hello World",
  74    *        attributes: null
  75    *      },
  76    *      {
  77    *        value: "You have 5 unread emails",
  78    *        attributes: {
  79    *          tooltip: "Click to select them all"
  80    *        }
  81    *      }
  82    *    ]);
  83    */
  84   [NewObject] Promise<sequence<DOMString>> formatMessages(sequence<L10nKey> aKeys);
  85
  86   /**
  87    * A helper function which allows the user to set localization-specific attributes
  88    * on an element.
  89    * This method lives on `document.l10n` for compatibility reasons with the
  90    * JS FluentDOM implementation. We may consider moving it onto Element.
  91    *
  92    * Example:
  93    *    document.l10n.setAttributes(h1, "key1", { emailCount: 5 });
  94    *
  95    *    <h1 data-l10n-id="key1" data-l10n-args="{\"emailCount\": 5}"/>
  96    */
  97   [Throws] void setAttributes(Element aElement, DOMString aId, optional object aArgs);
  98
  99   /**
 100    * A helper function which allows the user to retrieve a set of localization-specific
 101    * attributes from an element.
 102    * This method lives on `document.l10n` for compatibility reasons with the
 103    * JS FluentDOM implementation. We may consider moving it onto Element.
 104    *
 105    * Example:
 106    *    let l10nAttrs = document.l10n.getAttributes(h1);
 107    *    assert.deepEqual(l10nAttrs, {id: "key1", args: { emailCount: 5});
 108    */
 109   [Throws] L10nKey getAttributes(Element aElement);
 110
 111   /**
 112    * Triggers translation of a subtree rooted at aNode.
 113    *
 114    * The method finds all translatable descendants of the argument and
 115    * localizes them.
 116    *
 117    * This method is mainly useful to trigger translation not covered by the
 118    * DOMLocalization's MutationObserver - for example before it gets attached
 119    * to the tree.
 120    *
 121    * Example:
 122    *    await document.l10n.translatFragment(frag);
 123    *    parent.appendChild(frag);
 124    */
 125   [NewObject] Promise<void> translateFragment(Node aNode);
 126
 127   /**
 128    * Triggers translation of a list of Elements using the localization context.
 129    *
 130    * The method only translates the elements directly passed to the method,
 131    * not any descendant nodes.
 132    *
 133    * This method is mainly useful to trigger translation not covered by the
 134    * DOMLocalization's MutationObserver - for example before it gets attached
 135    * to the tree.
 136    *
 137    * Example:
 138    *    await document.l10n.translateElements([elem1, elem2]);
 139    *    parent.appendChild(elem1);
 140    *    alert(elem2.textContent);
 141    */
 142   [NewObject] Promise<void> translateElements(sequence<Element> aElements);
 143
 144   /**
 145    * A promise which gets resolved when the initial DOM localization resources
 146    * fetching is complete and the initial translation of the DOM is finished.
 147    */
 148   readonly attribute Promise<any> ready;
 149 };