tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

L10nRegistry.webidl (6157B)

      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 };