intl/locale/mozILocaleService.idl

   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)]
  17 interface 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 };