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 [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 };