dom/chrome-webidl/L10nRegistry.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 dictionary L10nFileSourceMockFile {
   7   required UTF8String path;
   8   required UTF8String source;
   9 };
  10
  11 enum L10nFileSourceHasFileStatus {
  12     "present",
  13     "missing",
  14     "unknown"
  15 };
  16
  17 dictionary FileSourceOptions {
  18   FluentBundleAddResourceOptions addResourceOptions = {};
  19 };
  20
  21 /**
  22  * A `ResourceId` refers to a localization resource that is either required
  23  * or optional. The default for a `ResourceId` is that the resource is required.
  24  *
  25  * If a required resource is missing for a given locale, then the L10nRegistry
  26  * will not generate a bundle for that locale, because the resource is required
  27  * to be present in order for the bundle to be considered valid.
  28  *
  29  * If an optional resource is missing for a given locale, then the L10nRegistry
  30  * will still generate a bundle for that locale, but entries for the missing
  31  * optional resource will be missing in the bundle.
  32  *
  33  * It is recommended to only use this sparingly, since marking many resources as
  34  * optional will increase the state space that the L10nRegistry solver has to cover,
  35  * and it will have a negative impact on performance.
  36  *
  37  * We should also strive to have valid resources for all supported locales, so using
  38  * optional resources should be reserved for exceptional circumstances such as
  39  * experimental features and features under development.
  40  */
  41 dictionary ResourceId {
  42   required UTF8String path;
  43   boolean _optional = false;
  44 };
  45
  46 typedef (UTF8String or ResourceId) L10nResourceId;
  47
  48 /**
  49  * The interface represents a single source location for
  50  * the registry.
  51  *
  52  * Examples of sources are:
  53  *  * Toolkit omni.ja Localization Directory
  54  *  * Browser omni.ja Localization Directory
  55  *  * Language Pack Toolkit Localization Directory
  56  *  * Language Pack Browser Localization Directory
  57  */
  58 [ChromeOnly,
  59  Exposed=Window]
  60 interface L10nFileSource {
  61   /**
  62    * The `name` is the name of the `L10nFileSource`.
  63    *
  64    * The `metaSource` is the name of the package that contains the
  65    * `L10nFileSource`, e.g. `app` for sources packaged with the browser, or
  66    * `langpack` for sources packaged in an addon.
  67    *
  68    * The `locales` is a list of locales for which resources are contained in
  69    * the `L10nFileSource`.
  70    *
  71    * The `prePath` is the path prefix for files contained in the `L10nFileSource`.
  72    *
  73    * Optional argument `index` can be used to provide a list
  74    * of files available in the source.
  75    *
  76    * This is particularly useful for custom file sources which
  77    * provide a small number of known override files allowing the
  78    * registry to avoid trying I/O on the source for all
  79    * files not available in the source.
  80    */
  81   [Throws]
  82   constructor(UTF8String name, UTF8String metaSource, sequence<UTF8String> locales, UTF8String prePath, optional FileSourceOptions options = {}, optional sequence<UTF8String> index);
  83
  84   /**
  85    * Tests may want to introduce custom file sources and
  86    * register them in a custom `L10nRegistry` to mock
  87    * behavior of using localization with test file sources.
  88    *
  89    * # Example:
  90    *
  91    * ```
  92    * let fs = [
  93    *   {
  94    *     "path": "/localization/en-US/test.ftl",
  95    *     "source": "key = Hello World!",
  96    *   }
  97    * ];
  98    * let mockSource = L10nFileSource.createMock("mock", "app", ["en-US"], "/localization/{locale}/", fs);
  99    *
 100    * let reg = new L10nRegistry();
 101    * reg.registerSources([mockSource]);
 102    *
 103    * let loc = new Localization(["test.ftl"], reg);
 104    * let value = await loc.formatValue("key");
 105    * assert(value, "Hello World!");
 106    * ```
 107    */
 108   [Throws]
 109   static L10nFileSource createMock(UTF8String name, UTF8String metasource, sequence<UTF8String> locales, UTF8String prePath, sequence<L10nFileSourceMockFile> fs);
 110
 111   readonly attribute UTF8String name;
 112   readonly attribute UTF8String metaSource;
 113   [Pure, Cached, Frozen]
 114   readonly attribute sequence<UTF8String> locales;
 115   /**
 116    * `prePath` is the root path used together with a relative path to construct the full path used to retrieve a file
 117    * out of a file source.
 118    *
 119    * The `prePath` will usually contain a placeholder `{locale}` which gets replaced with a given locale.
 120    */
 121   readonly attribute UTF8String prePath;
 122   [Pure, Cached, Frozen]
 123   readonly attribute sequence<UTF8String>? index;
 124
 125   [Throws]
 126   L10nFileSourceHasFileStatus hasFile(UTF8String locale, UTF8String path);
 127   [NewObject]
 128   Promise<FluentResource?> fetchFile(UTF8String locale, UTF8String path);
 129   [Throws]
 130   FluentResource? fetchFileSync(UTF8String locale, UTF8String path);
 131 };
 132
 133 dictionary FluentBundleIteratorResult
 134 {
 135   required FluentBundle? value;
 136   required boolean done;
 137 };
 138
 139 [LegacyNoInterfaceObject, Exposed=Window]
 140 interface FluentBundleIterator {
 141   FluentBundleIteratorResult next();
 142   [Alias="@@iterator"] FluentBundleIterator values();
 143 };
 144
 145 [LegacyNoInterfaceObject, Exposed=Window]
 146 interface FluentBundleAsyncIterator {
 147   [NewObject]
 148   Promise<FluentBundleIteratorResult> next();
 149   [Alias="@@asyncIterator"] FluentBundleAsyncIterator values();
 150 };
 151
 152 dictionary L10nRegistryOptions {
 153   FluentBundleOptions bundleOptions = {};
 154 };
 155
 156 [ChromeOnly, Exposed=Window]
 157 interface L10nRegistry {
 158   constructor(optional L10nRegistryOptions aOptions = {});
 159
 160   static L10nRegistry getInstance();
 161
 162   sequence<UTF8String> getAvailableLocales();
 163
 164   undefined registerSources(sequence<L10nFileSource> aSources);
 165   undefined updateSources(sequence<L10nFileSource> aSources);
 166   undefined removeSources(sequence<UTF8String> aSources);
 167
 168   [Throws]
 169   boolean hasSource(UTF8String aName);
 170   [Throws]
 171   L10nFileSource? getSource(UTF8String aName);
 172   sequence<UTF8String> getSourceNames();
 173   undefined clearSources();
 174
 175   [Throws, NewObject]
 176   FluentBundleIterator generateBundlesSync(sequence<UTF8String> aLocales, sequence<L10nResourceId> aResourceIds);
 177
 178   [Throws, NewObject]
 179   FluentBundleAsyncIterator generateBundles(sequence<UTF8String> aLocales, sequence<L10nResourceId> aResourceIds);
 180 };