Localization.webidl (5251B)
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 * L10nIdArgs is an object used to carry localization tuple for message 8 * translation. 9 * 10 * Fields: 11 * id - identifier of a message. 12 * args - an optional record of arguments used to format the message. 13 * The argument will be converted to/from JSON, and the API 14 * will only handle strings and numbers. 15 */ 16 dictionary L10nIdArgs { 17 UTF8String? id = null; 18 L10nArgs? args = null; 19 }; 20 21 /** 22 * When no arguments are required to format a message a simple string can be 23 * used instead. 24 */ 25 typedef (UTF8String or L10nIdArgs) L10nKey; 26 27 /** 28 * L10nMessage is a compound translation unit from Fluent which 29 * encodes the value and (optionally) a list of attributes used 30 * to translate a given widget. 31 * 32 * Most simple imperative translations will only use the `value`, 33 * but when building a Message for a UI widget, a combination 34 * of a value and attributes will be used. 35 */ 36 dictionary AttributeNameValue { 37 required UTF8String name; 38 required UTF8String value; 39 }; 40 41 dictionary L10nMessage { 42 UTF8String? value = null; 43 sequence<AttributeNameValue>? attributes = null; 44 }; 45 46 /** 47 * Localization is an implementation of the Fluent Localization API. 48 * 49 * An instance of a Localization class stores a state of a mix 50 * of localization resources and provides the API to resolve 51 * translation value for localization identifiers from the 52 * resources. 53 * 54 * Methods: 55 * - addResourceIds - add resources 56 * - removeResourceIds - remove resources 57 * - formatValue - format a single value 58 * - formatValues - format multiple values 59 * - formatMessages - format multiple compound messages 60 * 61 */ 62 [Func="mozilla::intl::Localization::IsAPIEnabled", Exposed=Window] 63 interface Localization { 64 /** 65 * Constructor arguments: 66 * - aResourceids - a list of localization resource URIs 67 * which will provide messages for this 68 * Localization instance. 69 * - aSync - Specifies if the initial state of the Localization API is synchronous. 70 * This enables a number of synchronous methods on the 71 * Localization API. 72 * - aRegistry - optional custom L10nRegistry to be used by this Localization instance. 73 * - aLocales - custom set of locales to be used for this Localization. 74 */ 75 [Throws] 76 constructor(sequence<L10nResourceId> aResourceIds, 77 optional boolean aSync = false, 78 optional L10nRegistry aRegistry, 79 optional sequence<UTF8String> aLocales); 80 81 /** 82 * A method for adding resources to the localization context. 83 */ 84 undefined addResourceIds(sequence<L10nResourceId> aResourceIds); 85 86 /** 87 * A method for removing resources from the localization context. 88 * 89 * Returns a new count of resources used by the context. 90 */ 91 unsigned long removeResourceIds(sequence<L10nResourceId> aResourceIds); 92 93 /** 94 * Formats a value of a localization message with a given id. 95 * An optional dictionary of arguments can be passed to inform 96 * the message formatting logic. 97 * 98 * Example: 99 * let value = await document.l10n.formatValue("unread-emails", {count: 5}); 100 * assert.equal(value, "You have 5 unread emails"); 101 */ 102 [NewObject] Promise<UTF8String?> formatValue(UTF8String aId, optional L10nArgs aArgs); 103 104 /** 105 * Formats values of a list of messages with given ids. 106 * 107 * Example: 108 * let values = await document.l10n.formatValues([ 109 * {id: "hello-world"}, 110 * {id: "unread-emails", args: {count: 5} 111 * ]); 112 * assert.deepEqual(values, [ 113 * "Hello World", 114 * "You have 5 unread emails" 115 * ]); 116 */ 117 [NewObject] Promise<sequence<UTF8String?>> formatValues(sequence<L10nKey> aKeys); 118 119 /** 120 * Formats values and attributes of a list of messages with given ids. 121 * 122 * Example: 123 * let values = await document.l10n.formatMessages([ 124 * {id: "hello-world"}, 125 * {id: "unread-emails", args: {count: 5} 126 * ]); 127 * assert.deepEqual(values, [ 128 * { 129 * value: "Hello World", 130 * attributes: null 131 * }, 132 * { 133 * value: "You have 5 unread emails", 134 * attributes: { 135 * tooltip: "Click to select them all" 136 * } 137 * } 138 * ]); 139 */ 140 [NewObject] Promise<sequence<L10nMessage?>> formatMessages(sequence<L10nKey> aKeys); 141 142 undefined setAsync(); 143 144 [NewObject, Throws] 145 UTF8String? formatValueSync(UTF8String aId, optional L10nArgs aArgs); 146 [NewObject, Throws] 147 sequence<UTF8String?> formatValuesSync(sequence<L10nKey> aKeys); 148 [NewObject, Throws] 149 sequence<L10nMessage?> formatMessagesSync(sequence<L10nKey> aKeys); 150 }; 151 152 /** 153 * A helper dict for converting between JS Value and L10nArgs. 154 */ 155 [GenerateInitFromJSON, GenerateConversionToJS] 156 dictionary L10nArgsHelperDict { 157 required L10nArgs args; 158 };