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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
|
/*
*****************************************************************************************
* Copyright (C) 2014-2015 Apple Inc. All Rights Reserved.
*****************************************************************************************
*/
#ifndef UALOC_H
#define UALOC_H
#include <_foundation_unicode/utypes.h>
#ifndef U_HIDE_DRAFT_API
/**
* Codes for language status in a country or region.
* @draft ICU 54
*/
typedef enum {
/**
* The status is unknown, or the language has no special status.
* @draft ICU 54 */
UALANGSTATUS_UNSPECIFIED = 0,
/**
* The language is official in a region of the specified country,
* e.g. Hawaiian for U.S.
* @draft ICU 54 */
UALANGSTATUS_REGIONAL_OFFICIAL = 4,
/**
* The language is de-facto official for the specified country or region,
* e.g. English for U.S.
* @draft ICU 54 */
UALANGSTATUS_DEFACTO_OFFICIAL = 8,
/**
* The language is explicitly official for the specified country or region.
* @draft ICU 54 */
UALANGSTATUS_OFFICIAL = 12
} UALanguageStatus;
/**
* UALANGDATA_CODELEN is the maximum length of a language code
* (language subtag, possible extension, possible script subtag)
* in the UALanguageEntry struct.
* @draft ICU 54
*/
#define UALANGDATA_CODELEN 23
/**
* The UALanguageEntry structure provides information about
* one of the languages for a specified region.
* @draft ICU 54
*/
typedef struct {
char languageCode[UALANGDATA_CODELEN + 1]; /**< language code, may include script or
other subtags after primary language.
This may be "und" (undetermined) for
some regions such as AQ Antarctica.
@draft ICU 54 */
double userFraction; /**< fraction of region's population (from 0.0 to 1.0) that
uses this language (not necessarily as a first language).
This may be 0.0 if the fraction is known to be very small.
@draft ICU 54 */
UALanguageStatus status; /**< status of the language, if any.
@draft ICU 54 */
} UALanguageEntry;
/**
* Fills out a provided UALanguageEntry entry with information about the languages
* used in a specified region.
*
* @param regionID
* The specified regionID (currently only ISO-3166-style IDs are supported).
* @param minimumFraction
* The minimum fraction of language users for a language to be included
* in the UALanguageEntry array. Must be in the range 0.0 to 1.0; set to
* 0.0 if no minimum threshold is desired. As an example, as of March 2014
* ICU lists 74 languages for India; setting minimumFraction to 0.001 (0.1%)
* skips 27, keeping the top 47 languages for inclusion in the entries array
* (depending on entriesCapacity); setting minimumFraction to 0.01 (1%)
* skips 54, keeping the top 20 for inclusion.
* @param entries
* Caller-provided array of UALanguageEntry elements. This will be filled
* out with information for languages of the specified region that meet
* the minimumFraction threshold, sorted in descending order by
* userFraction, up to the number of elements specified by entriesCapacity
* (so the number of languages for which data is provided can be limited by
* total count, by userFraction, or both).
* Preflight option: You may set this to NULL (and entriesCapacity to 0)
* to just obtain a count of all of the languages that meet the specified
* minimumFraction, without actually getting data for any of them.
* @param entriesCapacity
* The number of elements in the provided entries array. Must be 0 if
* entries is NULL (preflight option).
* @param status
* A pointer to a UErrorCode to receive any errors, for example
* U_MISSING_RESOURCE_ERROR if there is no data available for the
* specified region.
* @return
* The number of elements in entries filled out with data, or if
* entries is NULL and entriesCapacity is 0 (preflight option ), the total
* number of languages for the specified region that meet the minimumFraction
* threshold.
* @draft ICU 54
*/
U_DRAFT int32_t U_EXPORT2
ualoc_getLanguagesForRegion(const char *regionID, double minimumFraction,
UALanguageEntry *entries, int32_t entriesCapacity,
UErrorCode *err);
/**
* UAREGIONDATA_CODELEN is the maximum length of a region code
* in the UARegionEntry struct. (This should be the same as ULOC_COUNTRY_CAPACITY, which
* is in a header we don't want to include here.)
* @draft ICU 68
*/
#define UAREGIONDATA_CODELEN 4
/**
* The UARegionEntry structure provides information about
* one of the languages for a specified region.
* @draft ICU 68
*/
typedef struct {
char regionCode[UAREGIONDATA_CODELEN]; /**< region code
@draft ICU 68 */
double userFraction; /**< fraction of region's population (from 0.0 to 1.0) that
uses this language (not necessarily as a first language).
This may be 0.0 if the fraction is known to be very small.
@draft ICU 68 */
UALanguageStatus status; /**< status of the language, if any.
@draft ICU 68 */
} UARegionEntry;
/**
* Fills out a provided UARegionEntry entry with information about the regions where the spceified
* language is spoken.
*
* @param languageID
* The specified language ID. This can be a two- or three-character language ID,
* or a combination of language and script IDs.
* @param minimumFraction
* The minimum fraction of language users for a region to be included
* in the UARegionEntry array. Must be in the range 0.0 to 1.0; set to
* 0.0 if no minimum threshold is desired.
* @param entries
* Caller-provided array of UARegionEntry elements. This will be filled
* out with information for regions for which the specified language meets
* the minimumFraction threshold, sorted in descending order by
* userFraction, up to the number of elements specified by entriesCapacity
* (so the number of languages for which data is provided can be limited by
* total count, by userFraction, or both).
* Preflight option: You may set this to NULL (and entriesCapacity to 0)
* to just obtain a count of all of the languages that meet the specified
* minimumFraction, without actually getting data for any of them.
* @param entriesCapacity
* The number of elements in the provided entries array. Must be 0 if
* entries is NULL (preflight option).
* @param status
* A pointer to a UErrorCode to receive any errors, for example
* U_MISSING_RESOURCE_ERROR if there is no data available for the
* specified region.
* @return
* The number of elements in entries filled out with data, or if
* entries is NULL and entriesCapacity is 0 (preflight option ), the total
* number of languages for the specified region that meet the minimumFraction
* threshold.
* @draft ICU 68
*/
U_DRAFT int32_t U_EXPORT2
ualoc_getRegionsForLanguage(const char *languageID, double minimumFraction,
UARegionEntry *entries, int32_t entriesCapacity,
UErrorCode *err);
/**
* Gets the desired lproj parent locale ID for the specified locale,
* using ICU inheritance chain plus Apple additions (for zh*). For
* example, provided any ID in the following chains it would return
* the next one to the right:
*
* en_US → en → root;
* en_HK → en_GB → en_001 → en → root;
* en_IN → en_GB → en_001 → en → root;
* es_ES → es → root;
* es_MX → es_419 → es → root;
* haw → root;
* pt_BR → pt → root;
* pt_PT → pt → root;
* sr_Cyrl → sr → root;
* sr_Latn → root;
* zh_Hans → zh → zh_CN → root;
* zh_Hant_MO → zh_Hant_HK → zh_Hant → zh_TW → root;
* zh_HK → zh_Hant_HK → zh_Hant → zh_TW → root;
* root → root;
* tlh → root;
*
* @param localeID The locale whose parent to get. This can use either '-' or '_' for separator.
* @param parent Buffer into which the parent localeID will be copied.
* This will always use '_' for separator.
* @param parentCapacity The size of the buffer for parent localeID (including room for null terminator).
* @param err Pointer to UErrorCode. If on input it indicates failure, function will return 0.
* If on output it indicates an error the contents of parent buffer are undefined.
* @return The actual buffer length of the parent localeID. If it is greater than parentCapacity,
* an overflow error will be set and the contents of parent buffer are undefined.
* @draft ICU 53
*/
U_DRAFT int32_t U_EXPORT2
ualoc_getAppleParent(const char* localeID,
char * parent,
int32_t parentCapacity,
UErrorCode* err);
/**
* ualoc_localizationsToUse - map preferred languages to
* available localizations.
* =========================
* BEHAVIOR EXAMPLES
* Each block gives up to 6 sets of available lprojs, and then shows how various
* preferred language requests would be mapped into one of the lprojs in each set.
* The en entriy marked * is currently not working as intended (get just "en"
* instead of the indicated values)
*
* --------
* lproj sets → list1 list2 list3 list4 list5 list6
* zh_CN zh_CN zh_CN zh_Hans zh_CN zh_CN
* zh_TW zh_TW zh_TW zh_Hant zh_TW zh_TW
* zh_HK zh_HK zh_Hant_HK zh_Hans zh_HK
* zh_MO zh_Hant zh_Hans
* zh_Hant
* zh_Hant_HK
* language ↓
* zh zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans
* zh-Hans zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans
* zh-Hant zh_TW zh_TW zh_TW zh_Hant zh_Hant zh_Hant
* zh-Hans-CN zh_CN zh_CN zh_CN zh_Hans zh_CN, zh_CN,
* zh_Hans zh_Hans
* zh-Hans-SG zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans
* zh-Hant-TW zh_TW zh_TW zh_TW zh_Hant zh_TW, zh_TW,
* zh_Hant zh_Hant
* zh-Hant-HK zh_TW zh_HK, zh_HK, zh_Hant_HK, zh_Hant zh_Hant_HK,
* zh_TW zh_TW zh_Hant zh_Hant
* zh-Hant-MO zh_TW zh_HK, zh_MO, zh_Hant_HK, zh_Hant zh_Hant_HK,
* zh_TW zh_HK,zh_TW zh_Hant zh_Hant
* zh-Hans-HK zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans
* zh-CN zh_CN zh_CN zh_CN zh_Hans zh_CN, zh_CN,
* zh_Hans zh_Hans
* zh-SG zh_CN zh_CN zh_CN zh_Hans zh_Hans zh_Hans
* zh-TW zh_TW zh_TW zh_TW zh_Hant zh_TW, zh_TW,
* zh_Hant zh_Hant
* zh-HK zh_TW zh_HK zh_HK, zh_Hant_HK, zh_Hant zh_HK,
* zh_TW zh_Hant zh_Hant_HK,zh_Hant
* zh-MO zh_TW zh_HK zh_MO, zh_Hant_HK, zh_Hant zh_Hant_HK,
* zh_HK,zh_TW zh_Hant zh_Hant_HK,zh_Hant
* --------
* lproj sets → list1 list2 list3 list4 list5 list6
* English en en en en en
* en_AU en_AU en_AU en_AU en_AU
* en_GB en_GB en_GB en_GB en_GB
* en_CA en_CA en_001 en_001
* en_IN en_150
* en_US
* language ↓
* en English en en en en en
* en-US English en en en_US, en en
* en
* en-AU English en_AU, en_AU, en_AU, en_AU,en_GB, en_AU,en_GB,
* en_GB,en en_GB,en en_GB,en en_001,en en_001,en
* en-CA English en en_CA, en_CA, en_001, en_001,
* en en en en
* en-GB English en_GB, en_GB, en_GB, en_GB, en_GB,
* en en en en_001,en en_001,en
* en-IN English en_GB, en_GB, en_IN, en_GB, en_GB,
* en en en_GB,en en_001,en en_001,en
* en-US English en en en_US, en en
* en
* en-FR English en_GB, en_GB, en_GB, en_GB, en_150,en_GB,
* en en en en_001,en en_001,en
* en-IL English en en en en_001, en_001,
* en en
* en-001 English en en en en_001, en_001,
* en en
* en-150 English en_GB, en_GB, en_GB, en_GB, en_150,en_GB,
* en en en en_001,en en_001,en
* en-Latn English en en en en en
* en-Latn_US English en en en_US,* en en
* en
* --------
* lproj sets → list1 list2 list3 list4 list5 list6
* Spanish es es es es es
* es_MX es_419 es_419 es_ES es_ES
* es_MX es_MX es_419
* es_MX
* language ↓
* es Spanish es es es es es
* es-ES Spanish es es es es_ES, es_ES,
* es es
* es-419 Spanish es es_419, es_419, es es_419,
* es es es
* es-MX Spanish es_MX, es_419, es_MX, es_MX, es_MX,
* es es es_419,es es es_419,es
* es-AR Spanish es es_419, es_419, es es_419,
* es es es
* --------
* lproj sets → list1 list2 list3 list4 list5 list6
* Portuguese pt pt pt
* pt_PT pt_BR pt_BR
* pt_PT
* language ↓
* pt Portuguese pt pt pt
* pt-BR Portuguese pt pt_BR, pt_BR,
* pt pt
* pt-PT Portuguese pt_PT, pt_PT, pt
* pt pt
* pt-MO Portuguese pt_PT, pt_PT, pt
* pt pt
* =========================
*
* @param preferredLanguages
* Ordered array of pointers to user's preferred language
* codes (BCP47 style null-terminated ASCII strings), in
* order from most preferred; intended to accept the
* contents of AppleLanguages. Must not be NULL.
* Entries with the following values will be ignored:
* NULL, "", "root", any entry beginning with '-' or '_'.
* @param preferredLanguagesCount
* Count of entries in preferredLanguages.
* @param availableLocalizations
* Unordered array of pointers to identifiers for available
* localizations (lprojs); handles old Apple-style
* identifiers such as "English", as well as currently-
* superseded identifiers such as "no", "tl". Must not be
* NULL. Entries with the following values will be ignored:
* NULL, "", "root", any entry beginning with '-' or '_'.
* "zxx" (meaning "no linguistic content") is a special value--
* If this is included in availableLocalizations and there are no
* matches between availableLocalizations and preferredLanguages,
* the result set will contain "zxx".
* @param availableLocalizationsCount
* Count of entries in availableLocalizations.
* @param localizationsToUse
* Caller-provided array to be filled with pointers to
* localizations to use in the availableLocalizations
* array; these are entries from availableLocalizations
* that correspond to the first language in
* preferredLanguages for which there is any entry in
* availableLocalizations that is a reasonable match,
* with the best-matching localization first in
* localizationsToUse, followed by any other possible
* fallback localizations (for example, "en_IN" in
* preferredLanguages might produce { "en_GB, "en" } in
* localizationsToUse). Must not be NULL. This need not
* large enough to accomodate all of the localizations
* that might be returned; it is perfectly reasonable
* (and more efficient) to only provide an array with
* one entry, if that is all that you are planning to use.
* @param localizationsToUseCapacity
* The capacity of localizationsToUse.
* @param status
* A pointer to a UErrorCode to receive any errors.
* @return
* The number of entries filled out in localizationsToUse.
* @draft ICU 55
*/
U_DRAFT int32_t U_EXPORT2
ualoc_localizationsToUse( const char* const *preferredLanguages,
int32_t preferredLanguagesCount,
const char* const *availableLocalizations,
int32_t availableLocalizationsCount,
const char* *localizationsToUse,
int32_t localizationsToUseCapacity,
UErrorCode *status );
#endif /* U_HIDE_DRAFT_API */
#endif /*UALOC_H*/
|
