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