Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
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<UTF8String> locales, UTF8String prePath, optional FileSourceOptions options = {}, optional sequence<UTF8String> 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<UTF8String> locales, UTF8String prePath, sequence<L10nFileSourceMockFile> fs);
readonly attribute UTF8String name;
readonly attribute UTF8String metaSource;
[Pure, Cached, Frozen]
readonly attribute sequence<UTF8String> 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<UTF8String>? index;
[Throws]
L10nFileSourceHasFileStatus hasFile(UTF8String locale, UTF8String path);
[NewObject]
Promise<FluentResource?> 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<FluentBundleIteratorResult> next();
[Alias="@@asyncIterator"] FluentBundleAsyncIterator values();
};
dictionary L10nRegistryOptions {
FluentBundleOptions bundleOptions = {};
};
[ChromeOnly, Exposed=Window]
interface L10nRegistry {
constructor(optional L10nRegistryOptions aOptions = {});
static L10nRegistry getInstance();
sequence<UTF8String> getAvailableLocales();
undefined registerSources(sequence<L10nFileSource> aSources);
undefined updateSources(sequence<L10nFileSource> aSources);
undefined removeSources(sequence<UTF8String> aSources);
[Throws]
boolean hasSource(UTF8String aName);
[Throws]
L10nFileSource? getSource(UTF8String aName);
sequence<UTF8String> getSourceNames();
undefined clearSources();
[Throws, NewObject]
FluentBundleIterator generateBundlesSync(sequence<UTF8String> aLocales, sequence<L10nResourceId> aResourceIds);
[Throws, NewObject]
FluentBundleAsyncIterator generateBundles(sequence<UTF8String> aLocales, sequence<L10nResourceId> aResourceIds);
};