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