Source code

Revision control

Other Tools

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