DOMLocalization.webidl (6230B)
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/. */ 5 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 */ 26 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); 47 48 /** 49 * Adds a node to nodes observed for localization 50 * related changes. 51 */ 52 undefined connectRoot(Node aElement); 53 54 /** 55 * Removes a node from nodes observed for localization 56 * related changes. 57 */ 58 undefined disconnectRoot(Node aElement); 59 60 /** 61 * Pauses the MutationObserver set to observe 62 * localization related DOM mutations. 63 */ 64 undefined pauseObserving(); 65 66 /** 67 * Resumes the MutationObserver set to observe 68 * localization related DOM mutations. 69 */ 70 undefined resumeObserving(); 71 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); 84 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); 96 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); 114 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); 135 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); 157 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 };