| blob | 1eb64a9bb4c96abd90bb875bbf9ad799553d4a9f |
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 /**
7 * DOMLocalization is an extension of the Fluent Localization API.
8 *
9 * DOMLocalization adds a state for storing `roots` - DOM elements
10 * which translation status is controlled by the DOMLocalization
11 * instance and monitored for mutations.
12 * DOMLocalization also adds methods dedicated to DOM manipulation.
13 *
14 * Methods:
15 * - connectRoot - add a root
16 * - disconnectRoot - remove a root
17 * - pauseObserving - pause observing of roots
18 * - resumeObserving - resume observing of roots
19 * - setAttributes - set l10n attributes of an element
20 * - getAttributes - retrieve l10n attributes of an element
21 * - translateFragment - translate a DOM fragment
22 * - translateElements - translate a list of DOM elements
23 * - translateRoots - translate all attached roots
24 *
25 */
27 [Func="mozilla::intl::Localization::IsAPIEnabled", Exposed=Window]
28 interface DOMLocalization : Localization {
29 /**
30 * Constructor arguments:
31 * - aResourceids - a list of localization resource URIs
32 * which will provide messages for this
33 * Localization instance.
34 * - aSync - Specifies if the initial state of the DOMLocalization
35 * and the underlying Localization API is synchronous.
36 * This enables a number of synchronous methods on the
37 * Localization API and uses it for `TranslateElements`
38 * making the method return a synchronusly resolved promise.
39 * - aRegistry - optional custom L10nRegistry to be used by this Localization instance.
40 * - aLocales - custom set of locales to be used for this Localization.
41 */
42 [Throws]
43 constructor(sequence<L10nResourceId> aResourceIds,
44 optional boolean aSync = false,
45 optional L10nRegistry aRegistry,
46 optional sequence<UTF8String> aLocales);
48 /**
49 * Adds a node to nodes observed for localization
50 * related changes.
51 */
52 undefined connectRoot(Node aElement);
54 /**
55 * Removes a node from nodes observed for localization
56 * related changes.
57 */
58 undefined disconnectRoot(Node aElement);
60 /**
61 * Pauses the MutationObserver set to observe
62 * localization related DOM mutations.
63 */
64 undefined pauseObserving();
66 /**
67 * Resumes the MutationObserver set to observe
68 * localization related DOM mutations.
69 */
70 undefined resumeObserving();
72 /**
73 * A helper function which allows the user to set localization-specific attributes
74 * on an element.
75 * This method lives on `document.l10n` for compatibility reasons with the
76 * JS FluentDOM implementation. We may consider moving it onto Element.
77 *
78 * Example:
79 * document.l10n.setAttributes(h1, "key1", { emailCount: 5 });
80 *
81 * <h1 data-l10n-id="key1" data-l10n-args="{\"emailCount\": 5}"/>
82 */
83 [Throws] undefined setAttributes(Element aElement, DOMString aId, optional object? aArgs);
85 /**
86 * A helper function which allows the user to retrieve a set of localization-specific
87 * attributes from an element.
88 * This method lives on `document.l10n` for compatibility reasons with the
89 * JS FluentDOM implementation. We may consider moving it onto Element.
90 *
91 * Example:
92 * let l10nAttrs = document.l10n.getAttributes(h1);
93 * assert.deepEqual(l10nAttrs, {id: "key1", args: { emailCount: 5});
94 */
95 [Throws] L10nIdArgs getAttributes(Element aElement);
97 /**
98 * A helper function which allows the user to set the l10n args for an element. This
99 * is similar to the setAttributes method, but does not require the l10n ID.
100 *
101 * Example:
102 *
103 * <h1 data-l10n-id="key1" />
104 *
105 * document.l10n.setArgs(h1, { emailCount: 5 });
106 *
107 * <h1 data-l10n-id="key1" data-l10n-args="{\"emailCount\": 5}" />
108 *
109 * document.l10n.setArgs(h1);
110 *
111 * <h1 data-l10n-id="key1" />
112 */
113 [Throws] undefined setArgs(Element aElement, optional object? aArgs);
115 /**
116 * Triggers translation of a subtree rooted at aNode.
117 *
118 * The method finds all translatable descendants of the argument and
119 * localizes them.
120 *
121 * This method is mainly useful to trigger translation not covered by the
122 * DOMLocalization's MutationObserver - for example before it gets attached
123 * to the tree.
124 * In such cases, when the already-translated fragment gets
125 * injected into the observed root, one should `pauseObserving`,
126 * then append the fragment, and finally `resumeObserving`.
127 *
128 * Example:
129 * await document.l10n.translatFragment(frag);
130 * root.pauseObserving();
131 * parent.appendChild(frag);
132 * root.resumeObserving();
133 */
134 [NewObject] Promise<any> translateFragment(Node aNode);
136 /**
137 * Triggers translation of a list of Elements using the localization context.
138 *
139 * The method only translates the elements directly passed to the method,
140 * not any descendant nodes.
141 *
142 * This method is mainly useful to trigger translation not covered by the
143 * DOMLocalization's MutationObserver - for example before it gets attached
144 * to the tree.
145 * In such cases, when the already-translated fragment gets
146 * injected into the observed root, one should `pauseObserving`,
147 * then append the fragment, and finally `resumeObserving`.
148 *
149 * Example:
150 * await document.l10n.translateElements([elem1, elem2]);
151 * root.pauseObserving();
152 * parent.appendChild(elem1);
153 * root.resumeObserving();
154 * alert(elem2.textContent);
155 */
156 [NewObject] Promise<undefined> translateElements(sequence<Element> aElements);
158 /**
159 * Triggers translation of all attached roots and sets their
160 * locale info and directionality attributes.
161 *
162 * Example:
163 * await document.l10n.translateRoots();
164 */
165 [NewObject] Promise<undefined> translateRoots();
166 };