dom/webidl/Localization.webidl

   1 /* -*- Mode: C++; 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
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /**
   7  * L10nIdArgs is an object used to carry localization tuple for message
   8  * translation.
   9  *
  10  * Fields:
  11  *    id - identifier of a message.
  12  *  args - an optional record of arguments used to format the message.
  13  *         The argument will be converted to/from JSON, and the API
  14  *         will only handle strings and numbers.
  15  */
  16 dictionary L10nIdArgs {
  17   UTF8String? id = null;
  18   L10nArgs? args = null;
  19 };
  20
  21 /**
  22  * When no arguments are required to format a message a simple string can be
  23  * used instead.
  24  */
  25 typedef (UTF8String or L10nIdArgs) L10nKey;
  26
  27 /**
  28  * L10nMessage is a compound translation unit from Fluent which
  29  * encodes the value and (optionally) a list of attributes used
  30  * to translate a given widget.
  31  *
  32  * Most simple imperative translations will only use the `value`,
  33  * but when building a Message for a UI widget, a combination
  34  * of a value and attributes will be used.
  35  */
  36 dictionary AttributeNameValue {
  37   required UTF8String name;
  38   required UTF8String value;
  39 };
  40
  41 dictionary L10nMessage {
  42   UTF8String? value = null;
  43   sequence<AttributeNameValue>? attributes = null;
  44 };
  45
  46 /**
  47  * Localization is an implementation of the Fluent Localization API.
  48  *
  49  * An instance of a Localization class stores a state of a mix
  50  * of localization resources and provides the API to resolve
  51  * translation value for localization identifiers from the
  52  * resources.
  53  *
  54  * Methods:
  55  *    - addResourceIds     - add resources
  56  *    - removeResourceIds  - remove resources
  57  *    - formatValue        - format a single value
  58  *    - formatValues       - format multiple values
  59  *    - formatMessages     - format multiple compound messages
  60  *
  61  */
  62 [Func="IsChromeOrUAWidget", Exposed=Window]
  63 interface Localization {
  64   /**
  65    * Constructor arguments:
  66    *    - aResourceids         - a list of localization resource URIs
  67    *                             which will provide messages for this
  68    *                             Localization instance.
  69    *    - aSync                - Specifies if the initial state of the Localization API is synchronous.
  70    *                             This enables a number of synchronous methods on the
  71    *                             Localization API.
  72    *    - aRegistry            - optional custom L10nRegistry to be used by this Localization instance.
  73    *    - aLocales             - custom set of locales to be used for this Localization.
  74    */
  75   [Throws]
  76   constructor(sequence<L10nResourceId> aResourceIds,
  77               optional boolean aSync = false,
  78               optional L10nRegistry aRegistry,
  79               optional sequence<UTF8String> aLocales);
  80
  81   /**
  82    * A method for adding resources to the localization context.
  83    */
  84   undefined addResourceIds(sequence<L10nResourceId> aResourceIds);
  85
  86   /**
  87    * A method for removing resources from the localization context.
  88    *
  89    * Returns a new count of resources used by the context.
  90    */
  91   unsigned long removeResourceIds(sequence<L10nResourceId> aResourceIds);
  92
  93   /**
  94    * Formats a value of a localization message with a given id.
  95    * An optional dictionary of arguments can be passed to inform
  96    * the message formatting logic.
  97    *
  98    * Example:
  99    *    let value = await document.l10n.formatValue("unread-emails", {count: 5});
 100    *    assert.equal(value, "You have 5 unread emails");
 101    */
 102   [NewObject] Promise<UTF8String?> formatValue(UTF8String aId, optional L10nArgs aArgs);
 103
 104   /**
 105    * Formats values of a list of messages with given ids.
 106    *
 107    * Example:
 108    *    let values = await document.l10n.formatValues([
 109    *      {id: "hello-world"},
 110    *      {id: "unread-emails", args: {count: 5}
 111    *    ]);
 112    *    assert.deepEqual(values, [
 113    *      "Hello World",
 114    *      "You have 5 unread emails"
 115    *    ]);
 116    */
 117   [NewObject] Promise<sequence<UTF8String?>> formatValues(sequence<L10nKey> aKeys);
 118
 119   /**
 120    * Formats values and attributes of a list of messages with given ids.
 121    *
 122    * Example:
 123    *    let values = await document.l10n.formatMessages([
 124    *      {id: "hello-world"},
 125    *      {id: "unread-emails", args: {count: 5}
 126    *    ]);
 127    *    assert.deepEqual(values, [
 128    *      {
 129    *        value: "Hello World",
 130    *        attributes: null
 131    *      },
 132    *      {
 133    *        value: "You have 5 unread emails",
 134    *        attributes: {
 135    *          tooltip: "Click to select them all"
 136    *        }
 137    *      }
 138    *    ]);
 139    */
 140   [NewObject] Promise<sequence<L10nMessage?>> formatMessages(sequence<L10nKey> aKeys);
 141
 142   undefined setAsync();
 143
 144   [NewObject, Throws]
 145   UTF8String? formatValueSync(UTF8String aId, optional L10nArgs aArgs);
 146   [NewObject, Throws]
 147   sequence<UTF8String?> formatValuesSync(sequence<L10nKey> aKeys);
 148   [NewObject, Throws]
 149   sequence<L10nMessage?> formatMessagesSync(sequence<L10nKey> aKeys);
 150 };
 151
 152 /**
 153  * A helper dict for converting between JS Value and L10nArgs.
 154  */
 155 [GenerateInitFromJSON, GenerateConversionToJS]
 156 dictionary L10nArgsHelperDict {
 157   required L10nArgs args;
 158 };