mozILocaleService.idl (7119B)
1 /* -*- Mode: IDL; 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 #include "nsISupports.idl" 7 8 [scriptable, uuid(C27F8983-B48B-4D1A-92D7-FEB8106F212D)] 9 interface mozILocaleService : nsISupports 10 { 11 /** 12 * List of language negotiation strategies to use. 13 * For an example list of requested and available locales: 14 * 15 * Requested: ['es-MX', 'fr-FR'] 16 * Available: ['fr', 'fr-CA', 'es', 'es-MX', 'it'] 17 * DefaultLocale: ['en-US'] 18 * 19 * each of those strategies will build a different result: 20 * 21 * 22 * filtering (default) - 23 * Matches as many of the available locales as possible. 24 * 25 * Result: 26 * Supported: ['es-MX', 'es', 'fr', 'fr-CA', 'en-US'] 27 * 28 * matching - 29 * Matches the best match from the available locales for every requested 30 * locale. 31 * 32 * Result: 33 * Supported: ['es-MX', 'fr', 'en-US'] 34 * 35 * lookup - 36 * Matches a single best locale. This strategy always returns a list 37 * of the length 1 and requires a defaultLocale to be set. 38 * 39 * Result: 40 * Supported: ['es-MX'] 41 */ 42 const long langNegStrategyFiltering = 0; 43 const long langNegStrategyMatching = 1; 44 const long langNegStrategyLookup = 2; 45 46 /** 47 * Default locale of the browser. The locale we are guaranteed to have 48 * resources for that should be used as a last resort fallack in cases 49 * where requested locales do not match available locales. 50 */ 51 readonly attribute ACString defaultLocale; 52 53 /** 54 * Last fallback is the final fallback locale we're going to attempt if all 55 * else fails in any language negotiation or locale resource retrieval situations. 56 * 57 * At the moment it returns `en-US`. 58 */ 59 readonly attribute ACString lastFallbackLocale; 60 61 /** 62 * Returns a list of locales that the application should be localized to. 63 * 64 * The result is a ordered list of valid locale IDs and it should be 65 * used for all APIs that accept list of locales, like ECMA402 and L10n APIs. 66 * 67 * This API always returns at least one locale. 68 * 69 * When retrieving the locales for language negotiation and matching 70 * to language resources, use the language tag form. 71 * When retrieving the locales for Intl API or ICU locale settings, 72 * use the BCP47 form. 73 * 74 * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"] 75 */ 76 readonly attribute Array<ACString> appLocalesAsLangTags; 77 readonly attribute Array<ACString> appLocalesAsBCP47; 78 79 /** 80 * Returns a list of locales to use for any regional specific operations 81 * like date formatting, calendars, unit formatting etc. 82 * 83 * The result is a ordered list of valid locale IDs and it should be 84 * used for all APIs that accept list of locales, like ECMA402 and L10n APIs. 85 * 86 * This API always returns at least one locale. 87 * 88 * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"] 89 */ 90 readonly attribute Array<ACString> regionalPrefsLocales; 91 92 readonly attribute Array<ACString> webExposedLocales; 93 94 /** 95 * Negotiates the best locales out of a ordered list of requested locales and 96 * a list of available locales. 97 * 98 * Internally it uses the following naming scheme: 99 * 100 * Requested - locales requested by the user 101 * Available - locales for which the data is available 102 * Supported - locales negotiated by the algorithm 103 * 104 * Additionally, if defaultLocale is provided, it adds it to the end of the 105 * result list as a "last resort" locale. 106 * 107 * Strategy is one of the three strategies described at the top of this file. 108 * 109 * The result list is canonicalized and ordered according to the order 110 * of the requested locales. 111 * 112 * (See LocaleService.h for a more C++-friendly version of this.) 113 */ 114 Array<ACString> negotiateLanguages(in Array<AUTF8String> aRequested, 115 in Array<AUTF8String> aAvailable, 116 [optional] in ACString aDefaultLocale, 117 [optional] in long langNegStrategy); 118 119 /** 120 * Returns the best locale that the application should be localized to. 121 * 122 * The result is a valid locale ID and it should be 123 * used for all APIs that do not handle language negotiation. 124 * 125 * When retrieving the locales for language negotiation and matching 126 * to language resources, use the language tag form. 127 * When retrieving the locales for Intl API or ICU locale settings, 128 * use the BCP47 form. 129 * 130 * Where possible, appLocales* should be preferred over this API and 131 * all callsites should handle some form of "best effort" language 132 * negotiation to respect user preferences in case the use case does 133 * not have data for the first locale in the list. 134 * 135 * Example: "zh-Hans-HK" 136 */ 137 readonly attribute ACString appLocaleAsLangTag; 138 readonly attribute ACString appLocaleAsBCP47; 139 140 /** 141 * Returns a list of locales that the user requested the app to be 142 * localized to. 143 * 144 * The result is an ordered list of locale IDs which should be 145 * used as a requestedLocales input list for language negotiation. 146 * 147 * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"] 148 */ 149 attribute Array<ACString> requestedLocales; 150 151 /** 152 * Returns the top-requested locale from the user, or an empty string if none is set. 153 */ 154 readonly attribute ACString requestedLocale; 155 156 /** 157 * Returns a list of locales that the app can be localized to. 158 * 159 * The result is an unordered list of locale IDs which should be 160 * used as a availableLocales input list for language negotiation. 161 * 162 * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"] 163 */ 164 attribute Array<ACString> availableLocales; 165 166 /** 167 * Returns whether the current app locale is RTL. 168 */ 169 readonly attribute boolean isAppLocaleRTL; 170 171 /** 172 * Returns a list of locales packaged into the app bundle. 173 * 174 * Example: ["en-US", "de", "pl", "sr-Cyrl", "zh-Hans-HK"] 175 */ 176 readonly attribute Array<ACString> packagedLocales; 177 178 /** 179 * The unicode ellipsis char "…", or "...", depending on the current app locale. 180 */ 181 readonly attribute AString ellipsis; 182 183 /** 184 * If true, accesskeys should always be appended for the current app locale. 185 */ 186 readonly attribute boolean alwaysAppendAccesskeys; 187 188 /** 189 * If true, accesskeys should always be separated from the label. 190 */ 191 readonly attribute boolean insertSeparatorBeforeAccesskeys; 192 193 /** 194 * A comma-separated list of valid BCP 47 language tags. 195 */ 196 readonly attribute ACString acceptLanguages; 197 198 /** 199 * The initial setting of the language drop-down menu 200 * in the Fonts and Colors > Advanced preference panel. 201 * 202 * Takes one of the values of the menuitems in the "selectLangs" menulist in 203 * https://searchfox.org/firefox-main/source/browser/components/preferences/dialogs/fonts.xhtml 204 */ 205 readonly attribute ACString fontLanguageGroup; 206 };