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