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