summaryrefslogtreecommitdiffstats
path: root/dom/webidl/Localization.webidl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /dom/webidl/Localization.webidl
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'dom/webidl/Localization.webidl')
-rw-r--r--dom/webidl/Localization.webidl158
1 files changed, 158 insertions, 0 deletions
diff --git a/dom/webidl/Localization.webidl b/dom/webidl/Localization.webidl
new file mode 100644
index 0000000000..8eceec433b
--- /dev/null
+++ b/dom/webidl/Localization.webidl
@@ -0,0 +1,158 @@
+/* -*- 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/. */
+
+/**
+ * L10nIdArgs is an object used to carry localization tuple for message
+ * translation.
+ *
+ * Fields:
+ * id - identifier of a message.
+ * args - an optional record of arguments used to format the message.
+ * The argument will be converted to/from JSON, and the API
+ * will only handle strings and numbers.
+ */
+dictionary L10nIdArgs {
+ UTF8String? id = null;
+ L10nArgs? args = null;
+};
+
+/**
+ * When no arguments are required to format a message a simple string can be
+ * used instead.
+ */
+typedef (UTF8String or L10nIdArgs) L10nKey;
+
+/**
+ * L10nMessage is a compound translation unit from Fluent which
+ * encodes the value and (optionally) a list of attributes used
+ * to translate a given widget.
+ *
+ * Most simple imperative translations will only use the `value`,
+ * but when building a Message for a UI widget, a combination
+ * of a value and attributes will be used.
+ */
+dictionary AttributeNameValue {
+ required UTF8String name;
+ required UTF8String value;
+};
+
+dictionary L10nMessage {
+ UTF8String? value = null;
+ sequence<AttributeNameValue>? attributes = null;
+};
+
+/**
+ * Localization is an implementation of the Fluent Localization API.
+ *
+ * An instance of a Localization class stores a state of a mix
+ * of localization resources and provides the API to resolve
+ * translation value for localization identifiers from the
+ * resources.
+ *
+ * Methods:
+ * - addResourceIds - add resources
+ * - removeResourceIds - remove resources
+ * - formatValue - format a single value
+ * - formatValues - format multiple values
+ * - formatMessages - format multiple compound messages
+ *
+ */
+[Func="IsChromeOrUAWidget", Exposed=Window]
+interface Localization {
+ /**
+ * Constructor arguments:
+ * - aResourceids - a list of localization resource URIs
+ * which will provide messages for this
+ * Localization instance.
+ * - aSync - Specifies if the initial state of the Localization API is synchronous.
+ * This enables a number of synchronous methods on the
+ * Localization API.
+ * - aRegistry - optional custom L10nRegistry to be used by this Localization instance.
+ * - aLocales - custom set of locales to be used for this Localization.
+ */
+ [Throws]
+ constructor(sequence<L10nResourceId> aResourceIds,
+ optional boolean aSync = false,
+ optional L10nRegistry aRegistry,
+ optional sequence<UTF8String> aLocales);
+
+ /**
+ * A method for adding resources to the localization context.
+ */
+ undefined addResourceIds(sequence<L10nResourceId> aResourceIds);
+
+ /**
+ * A method for removing resources from the localization context.
+ *
+ * Returns a new count of resources used by the context.
+ */
+ unsigned long removeResourceIds(sequence<L10nResourceId> aResourceIds);
+
+ /**
+ * Formats a value of a localization message with a given id.
+ * An optional dictionary of arguments can be passed to inform
+ * the message formatting logic.
+ *
+ * Example:
+ * let value = await document.l10n.formatValue("unread-emails", {count: 5});
+ * assert.equal(value, "You have 5 unread emails");
+ */
+ [NewObject] Promise<UTF8String?> formatValue(UTF8String aId, optional L10nArgs aArgs);
+
+ /**
+ * Formats values of a list of messages with given ids.
+ *
+ * Example:
+ * let values = await document.l10n.formatValues([
+ * {id: "hello-world"},
+ * {id: "unread-emails", args: {count: 5}
+ * ]);
+ * assert.deepEqual(values, [
+ * "Hello World",
+ * "You have 5 unread emails"
+ * ]);
+ */
+ [NewObject] Promise<sequence<UTF8String?>> formatValues(sequence<L10nKey> aKeys);
+
+ /**
+ * Formats values and attributes of a list of messages with given ids.
+ *
+ * Example:
+ * let values = await document.l10n.formatMessages([
+ * {id: "hello-world"},
+ * {id: "unread-emails", args: {count: 5}
+ * ]);
+ * assert.deepEqual(values, [
+ * {
+ * value: "Hello World",
+ * attributes: null
+ * },
+ * {
+ * value: "You have 5 unread emails",
+ * attributes: {
+ * tooltip: "Click to select them all"
+ * }
+ * }
+ * ]);
+ */
+ [NewObject] Promise<sequence<L10nMessage?>> formatMessages(sequence<L10nKey> aKeys);
+
+ undefined setAsync();
+
+ [NewObject, Throws]
+ UTF8String? formatValueSync(UTF8String aId, optional L10nArgs aArgs);
+ [NewObject, Throws]
+ sequence<UTF8String?> formatValuesSync(sequence<L10nKey> aKeys);
+ [NewObject, Throws]
+ sequence<L10nMessage?> formatMessagesSync(sequence<L10nKey> aKeys);
+};
+
+/**
+ * A helper dict for converting between JS Value and L10nArgs.
+ */
+[GenerateInitFromJSON, GenerateConversionToJS]
+dictionary L10nArgsHelperDict {
+ required L10nArgs args;
+};