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/. */
6 dictionary L10nFileSourceMockFile {
7 required UTF8String path;
8 required UTF8String source;
11 enum L10nFileSourceHasFileStatus {
17 dictionary FileSourceOptions {
18 FluentBundleAddResourceOptions addResourceOptions = {};
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.
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.
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.
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.
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.
41 dictionary ResourceId {
42 required UTF8String path;
43 boolean _optional = false;
46 typedef (UTF8String or ResourceId) L10nResourceId;
49 * The interface represents a single source location for
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
60 interface L10nFileSource {
62 * The `name` is the name of the `L10nFileSource`.
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.
68 * The `locales` is a list of locales for which resources are contained in
69 * the `L10nFileSource`.
71 * The `prePath` is the path prefix for files contained in the `L10nFileSource`.
73 * Optional argument `index` can be used to provide a list
74 * of files available in the source.
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.
82 constructor(UTF8String name, UTF8String metaSource, sequence<UTF8String> locales, UTF8String prePath, optional FileSourceOptions options = {}, optional sequence<UTF8String> index);
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.
94 * "path": "/localization/en-US/test.ftl",
95 * "source": "key = Hello World!",
98 * let mockSource = L10nFileSource.createMock("mock", "app", ["en-US"], "/localization/{locale}/", fs);
100 * let reg = new L10nRegistry();
101 * reg.registerSources([mockSource]);
103 * let loc = new Localization(["test.ftl"], reg);
104 * let value = await loc.formatValue("key");
105 * assert(value, "Hello World!");
109 static L10nFileSource createMock(UTF8String name, UTF8String metasource, sequence<UTF8String> locales, UTF8String prePath, sequence<L10nFileSourceMockFile> fs);
111 readonly attribute UTF8String name;
112 readonly attribute UTF8String metaSource;
113 [Pure, Cached, Frozen]
114 readonly attribute sequence<UTF8String> locales;
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.
119 * The `prePath` will usually contain a placeholder `{locale}` which gets replaced with a given locale.
121 readonly attribute UTF8String prePath;
122 [Pure, Cached, Frozen]
123 readonly attribute sequence<UTF8String>? index;
126 L10nFileSourceHasFileStatus hasFile(UTF8String locale, UTF8String path);
128 Promise<FluentResource?> fetchFile(UTF8String locale, UTF8String path);
130 FluentResource? fetchFileSync(UTF8String locale, UTF8String path);
133 dictionary FluentBundleIteratorResult
135 required FluentBundle? value;
136 required boolean done;
139 [LegacyNoInterfaceObject, Exposed=Window]
140 interface FluentBundleIterator {
141 FluentBundleIteratorResult next();
142 [Alias="@@iterator"] FluentBundleIterator values();
145 [LegacyNoInterfaceObject, Exposed=Window]
146 interface FluentBundleAsyncIterator {
148 Promise<FluentBundleIteratorResult> next();
149 [Alias="@@asyncIterator"] FluentBundleAsyncIterator values();
152 dictionary L10nRegistryOptions {
153 FluentBundleOptions bundleOptions = {};
156 [ChromeOnly, Exposed=Window]
157 interface L10nRegistry {
158 constructor(optional L10nRegistryOptions aOptions = {});
160 static L10nRegistry getInstance();
162 sequence<UTF8String> getAvailableLocales();
164 undefined registerSources(sequence<L10nFileSource> aSources);
165 undefined updateSources(sequence<L10nFileSource> aSources);
166 undefined removeSources(sequence<UTF8String> aSources);
169 boolean hasSource(UTF8String aName);
171 L10nFileSource? getSource(UTF8String aName);
172 sequence<UTF8String> getSourceNames();
173 undefined clearSources();
176 FluentBundleIterator generateBundlesSync(sequence<UTF8String> aLocales, sequence<L10nResourceId> aResourceIds);
179 FluentBundleAsyncIterator generateBundles(sequence<UTF8String> aLocales, sequence<L10nResourceId> aResourceIds);