| /* |
| ***************************************************************************************** |
| * Copyright (C) 2014-2015 Apple Inc. All Rights Reserved. |
| ***************************************************************************************** |
| */ |
| |
| #ifndef UALOC_H |
| #define UALOC_H |
| |
| #include "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); |
| |
| |
| /** |
| * 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. |
| * @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*/ |
