From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- dom/chrome-webidl/L10nRegistry.webidl | 180 ++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 dom/chrome-webidl/L10nRegistry.webidl (limited to 'dom/chrome-webidl/L10nRegistry.webidl') diff --git a/dom/chrome-webidl/L10nRegistry.webidl b/dom/chrome-webidl/L10nRegistry.webidl new file mode 100644 index 0000000000..81932b2cd7 --- /dev/null +++ b/dom/chrome-webidl/L10nRegistry.webidl @@ -0,0 +1,180 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +dictionary L10nFileSourceMockFile { + required UTF8String path; + required UTF8String source; +}; + +enum L10nFileSourceHasFileStatus { + "present", + "missing", + "unknown" +}; + +dictionary FileSourceOptions { + FluentBundleAddResourceOptions addResourceOptions = {}; +}; + +/** + * A `ResourceId` refers to a localization resource that is either required + * or optional. The default for a `ResourceId` is that the resource is required. + * + * If a required resource is missing for a given locale, then the L10nRegistry + * will not generate a bundle for that locale, because the resource is required + * to be present in order for the bundle to be considered valid. + * + * If an optional resource is missing for a given locale, then the L10nRegistry + * will still generate a bundle for that locale, but entries for the missing + * optional resource will be missing in the bundle. + * + * It is recommended to only use this sparingly, since marking many resources as + * optional will increase the state space that the L10nRegistry solver has to cover, + * and it will have a negative impact on performance. + * + * We should also strive to have valid resources for all supported locales, so using + * optional resources should be reserved for exceptional circumstances such as + * experimental features and features under development. + */ +dictionary ResourceId { + required UTF8String path; + boolean _optional = false; +}; + +typedef (UTF8String or ResourceId) L10nResourceId; + +/** + * The interface represents a single source location for + * the registry. + * + * Examples of sources are: + * * Toolkit omni.ja Localization Directory + * * Browser omni.ja Localization Directory + * * Language Pack Toolkit Localization Directory + * * Language Pack Browser Localization Directory + */ +[ChromeOnly, + Exposed=Window] +interface L10nFileSource { + /** + * The `name` is the name of the `L10nFileSource`. + * + * The `metaSource` is the name of the package that contains the + * `L10nFileSource`, e.g. `app` for sources packaged with the browser, or + * `langpack` for sources packaged in an addon. + * + * The `locales` is a list of locales for which resources are contained in + * the `L10nFileSource`. + * + * The `prePath` is the path prefix for files contained in the `L10nFileSource`. + * + * Optional argument `index` can be used to provide a list + * of files available in the source. + * + * This is particularly useful for custom file sources which + * provide a small number of known override files allowing the + * registry to avoid trying I/O on the source for all + * files not available in the source. + */ + [Throws] + constructor(UTF8String name, UTF8String metaSource, sequence locales, UTF8String prePath, optional FileSourceOptions options = {}, optional sequence index); + + /** + * Tests may want to introduce custom file sources and + * register them in a custom `L10nRegistry` to mock + * behavior of using localization with test file sources. + * + * # Example: + * + * ``` + * let fs = [ + * { + * "path": "/localization/en-US/test.ftl", + * "source": "key = Hello World!", + * } + * ]; + * let mockSource = L10nFileSource.createMock("mock", "app", ["en-US"], "/localization/{locale}/", fs); + * + * let reg = new L10nRegistry(); + * reg.registerSources([mockSource]); + * + * let loc = new Localization(["test.ftl"], reg); + * let value = await loc.formatValue("key"); + * assert(value, "Hello World!"); + * ``` + */ + [Throws] + static L10nFileSource createMock(UTF8String name, UTF8String metasource, sequence locales, UTF8String prePath, sequence fs); + + readonly attribute UTF8String name; + readonly attribute UTF8String metaSource; + [Pure, Cached, Frozen] + readonly attribute sequence locales; + /** + * `prePath` is the root path used together with a relative path to construct the full path used to retrieve a file + * out of a file source. + * + * The `prePath` will usually contain a placeholder `{locale}` which gets replaced with a given locale. + */ + readonly attribute UTF8String prePath; + [Pure, Cached, Frozen] + readonly attribute sequence? index; + + [Throws] + L10nFileSourceHasFileStatus hasFile(UTF8String locale, UTF8String path); + [NewObject] + Promise fetchFile(UTF8String locale, UTF8String path); + [Throws] + FluentResource? fetchFileSync(UTF8String locale, UTF8String path); +}; + +dictionary FluentBundleIteratorResult +{ + required FluentBundle? value; + required boolean done; +}; + +[LegacyNoInterfaceObject, Exposed=Window] +interface FluentBundleIterator { + FluentBundleIteratorResult next(); + [Alias="@@iterator"] FluentBundleIterator values(); +}; + +[LegacyNoInterfaceObject, Exposed=Window] +interface FluentBundleAsyncIterator { + [NewObject] + Promise next(); + [Alias="@@asyncIterator"] FluentBundleAsyncIterator values(); +}; + +dictionary L10nRegistryOptions { + FluentBundleOptions bundleOptions = {}; +}; + +[ChromeOnly, Exposed=Window] +interface L10nRegistry { + constructor(optional L10nRegistryOptions aOptions = {}); + + static L10nRegistry getInstance(); + + sequence getAvailableLocales(); + + undefined registerSources(sequence aSources); + undefined updateSources(sequence aSources); + undefined removeSources(sequence aSources); + + [Throws] + boolean hasSource(UTF8String aName); + [Throws] + L10nFileSource? getSource(UTF8String aName); + sequence getSourceNames(); + undefined clearSources(); + + [Throws, NewObject] + FluentBundleIterator generateBundlesSync(sequence aLocales, sequence aResourceIds); + + [Throws, NewObject] + FluentBundleAsyncIterator generateBundles(sequence aLocales, sequence aResourceIds); +}; -- cgit v1.2.3