icuSources/common/unicode/ualoc.h

   1 /*
   2 *****************************************************************************************
   3 * Copyright (C) 2014-2015 Apple Inc. All Rights Reserved.
   4 *****************************************************************************************
   5 */
   6
   7 #ifndef UALOC_H
   8 #define UALOC_H
   9
  10 #include "unicode/utypes.h"
  11
  12 #ifndef U_HIDE_DRAFT_API
  13
  14 /**
  15  * Codes for language status in a country or region.
  16  * @draft ICU 54
  17  */
  18 typedef enum {
  19     /**
  20      * The status is unknown, or the language has no special status.
  21      * @draft ICU 54 */
  22     UALANGSTATUS_UNSPECIFIED       = 0,
  23     /**
  24      * The language is official in a region of the specified country,
  25      * e.g. Hawaiian for U.S.
  26      * @draft ICU 54 */
  27     UALANGSTATUS_REGIONAL_OFFICIAL = 4,
  28     /**
  29      * The language is de-facto official for the specified country or region,
  30      * e.g. English for U.S.
  31      * @draft ICU 54 */
  32     UALANGSTATUS_DEFACTO_OFFICIAL  = 8,
  33     /**
  34      * The language is explicitly official for the specified country or region.
  35      * @draft ICU 54 */
  36     UALANGSTATUS_OFFICIAL          = 12
  37 } UALanguageStatus;
  38
  39 /**
  40  * UALANGDATA_CODELEN is the maximum length of a language code
  41  * (language subtag, possible extension, possible script subtag)
  42  * in the UALanguageEntry struct.
  43  * @draft ICU 54
  44  */
  45 #define UALANGDATA_CODELEN 23
  46
  47 /**
  48  * The UALanguageEntry structure provides information about
  49  * one of the languages for a specified region.
  50  * @draft ICU 54
  51  */
  52 typedef struct {
  53     char languageCode[UALANGDATA_CODELEN + 1];  /**< language code, may include script or
  54                                                    other subtags after primary language.
  55                                                    This may be "und" (undetermined) for
  56                                                    some regions such as AQ Antarctica.
  57                                                    @draft ICU 54 */
  58     double userFraction;      /**< fraction of region's population (from 0.0 to 1.0) that
  59                                 uses this language (not necessarily as a first language).
  60                                 This may be 0.0 if the fraction is known to be very small.
  61                                 @draft ICU 54 */
  62     UALanguageStatus status;  /**< status of the language, if any.
  63                                 @draft ICU 54 */
  64 } UALanguageEntry;
  65
  66 /**
  67  * Fills out a provided UALanguageEntry entry with information about the languages
  68  * used in a specified region.
  69  *
  70  * @param regionID
  71  *          The specified regionID (currently only ISO-3166-style IDs are supported).
  72  * @param minimumFraction
  73  *          The minimum fraction of language users for a language to be included
  74  *          in the UALanguageEntry array. Must be in the range 0.0 to 1.0; set to
  75  *          0.0 if no minimum threshold is desired. As an example, as of March 2014
  76  *          ICU lists 74 languages for India; setting minimumFraction to 0.001 (0.1%)
  77  *          skips 27, keeping the top 47 languages for inclusion in the entries array
  78  *          (depending on entriesCapacity); setting minimumFraction to 0.01 (1%)
  79  *          skips 54, keeping the top 20 for inclusion.
  80  * @param entries
  81  *          Caller-provided array of UALanguageEntry elements. This will be filled
  82  *          out with information for languages of the specified region that meet
  83  *          the minimumFraction threshold, sorted in descending order by
  84  *          userFraction, up to the number of elements specified by entriesCapacity
  85  *          (so the number of languages for which data is provided can be limited by
  86  *          total count, by userFraction, or both).
  87  *          Preflight option: You may set this to NULL (and entriesCapacity to 0)
  88  *          to just obtain a count of all of the languages that meet the specified
  89  *          minimumFraction, without actually getting data for any of them.
  90  * @param entriesCapacity
  91  *          The number of elements in the provided entries array. Must be 0 if
  92  *          entries is NULL (preflight option).
  93  * @param status
  94  *          A pointer to a UErrorCode to receive any errors, for example
  95  *          U_MISSING_RESOURCE_ERROR if there is no data available for the
  96  *          specified region.
  97  * @return
  98  *          The number of elements in entries filled out with data, or if
  99  *          entries is NULL and entriesCapacity is 0 (preflight option ), the total
 100  *          number of languages for the specified region that meet the minimumFraction
 101  *          threshold.
 102  * @draft ICU 54
 103  */
 104 U_DRAFT int32_t U_EXPORT2
 105 ualoc_getLanguagesForRegion(const char *regionID, double minimumFraction,
 106                             UALanguageEntry *entries, int32_t entriesCapacity,
 107                             UErrorCode *err);
 108
 109
 110 /**
 111  * Gets the desired lproj parent locale ID for the specified locale,
 112  * using ICU inheritance chain plus Apple additions (for zh*). For
 113  * example, provided any ID in the following chains it would return
 114  * the next one to the right:
 115  *
 116  *                                 en_US → en → root;
 117  *                en_HK → en_GB → en_001 → en → root;
 118  *                en_IN → en_GB → en_001 → en → root;
 119  *                                 es_ES → es → root;
 120  *                        es_MX → es_419 → es → root;
 121  *                                        haw → root;
 122  *                                 pt_BR → pt → root;
 123  *                                 pt_PT → pt → root;
 124  *                               sr_Cyrl → sr → root;
 125  *                                    sr_Latn → root;
 126  *                       zh_Hans → zh → zh_CN → root;
 127  *  zh_Hant_MO → zh_Hant_HK → zh_Hant → zh_TW → root;
 128  *       zh_HK → zh_Hant_HK → zh_Hant → zh_TW → root;
 129  *                                       root → root;
 130  *                                        tlh → root;
 131  *
 132  * @param localeID  The locale whose parent to get. This can use either '-' or '_' for separator.
 133  * @param parent    Buffer into which the parent localeID will be copied.
 134  *                  This will always use '_' for separator.
 135  * @param parentCapacity  The size of the buffer for parent localeID (including room for null terminator).
 136  * @param err       Pointer to UErrorCode. If on input it indicates failure, function will return 0.
 137  *                  If on output it indicates an error the contents of parent buffer are undefined.
 138  * @return          The actual buffer length of the parent localeID. If it is greater than parentCapacity,
 139  *                  an overflow error will be set and the contents of parent buffer are undefined.
 140  * @draft ICU 53
 141  */
 142 U_DRAFT int32_t U_EXPORT2
 143 ualoc_getAppleParent(const char* localeID,
 144                      char * parent,
 145                      int32_t parentCapacity,
 146                      UErrorCode* err);
 147
 148 /**
 149  * ualoc_localizationsToUse - map preferred languages to
 150  * available localizations.
 151  * =========================
 152  *  BEHAVIOR EXAMPLES
 153  *  Each block gives up to 6 sets of available lprojs, and then shows how various
 154  *  preferred language requests would be mapped into one of the lprojs in each set.
 155  *  The en entriy marked * is currently not working as intended (get just "en"
 156  *  instead of the indicated values)
 157  *
 158  *  --------
 159  *  lproj sets →    list1       list2       list3       list4       list5        list6
 160  *                  zh_CN       zh_CN       zh_CN       zh_Hans     zh_CN        zh_CN
 161  *                  zh_TW       zh_TW       zh_TW       zh_Hant     zh_TW        zh_TW
 162  *                              zh_HK       zh_HK       zh_Hant_HK  zh_Hans      zh_HK
 163  *                                          zh_MO                   zh_Hant      zh_Hans
 164  *                                                                               zh_Hant
 165  *                                                                               zh_Hant_HK
 166  *  language ↓
 167  *  zh              zh_CN       zh_CN       zh_CN       zh_Hans     zh_Hans      zh_Hans
 168  *  zh-Hans         zh_CN       zh_CN       zh_CN       zh_Hans     zh_Hans      zh_Hans
 169  *  zh-Hant         zh_TW       zh_TW       zh_TW       zh_Hant     zh_Hant      zh_Hant
 170  *  zh-Hans-CN      zh_CN       zh_CN       zh_CN       zh_Hans     zh_CN,       zh_CN,
 171  *                                                                  zh_Hans      zh_Hans
 172  *  zh-Hans-SG      zh_CN       zh_CN       zh_CN       zh_Hans     zh_Hans      zh_Hans
 173  *  zh-Hant-TW      zh_TW       zh_TW       zh_TW       zh_Hant     zh_TW,       zh_TW,
 174  *                                                                  zh_Hant      zh_Hant
 175  *  zh-Hant-HK      zh_TW       zh_HK,      zh_HK,      zh_Hant_HK, zh_Hant      zh_Hant_HK,
 176  *                              zh_TW       zh_TW       zh_Hant                  zh_Hant
 177  *  zh-Hant-MO      zh_TW       zh_HK,      zh_MO,      zh_Hant_HK, zh_Hant      zh_Hant_HK,
 178  *                              zh_TW       zh_HK,zh_TW zh_Hant                  zh_Hant
 179  *  zh-Hans-HK      zh_CN       zh_CN       zh_CN       zh_Hans     zh_Hans      zh_Hans
 180  *  zh-CN           zh_CN       zh_CN       zh_CN       zh_Hans     zh_CN,       zh_CN,
 181  *                                                                  zh_Hans      zh_Hans
 182  *  zh-SG           zh_CN       zh_CN       zh_CN       zh_Hans     zh_Hans      zh_Hans
 183  *  zh-TW           zh_TW       zh_TW       zh_TW       zh_Hant     zh_TW,       zh_TW,
 184  *                                                                  zh_Hant      zh_Hant
 185  *  zh-HK           zh_TW       zh_HK       zh_HK,      zh_Hant_HK, zh_Hant      zh_HK,
 186  *                                          zh_TW       zh_Hant                  zh_Hant_HK,zh_Hant
 187  *  zh-MO           zh_TW       zh_HK       zh_MO,      zh_Hant_HK, zh_Hant      zh_Hant_HK,
 188  *                                          zh_HK,zh_TW zh_Hant                  zh_Hant_HK,zh_Hant
 189  *  --------
 190  *  lproj sets →    list1       list2       list3       list4       list5        list6
 191  *                  English     en          en          en          en           en
 192  *                              en_AU       en_AU       en_AU       en_AU        en_AU
 193  *                              en_GB       en_GB       en_GB       en_GB        en_GB
 194  *                                          en_CA       en_CA       en_001       en_001
 195  *                                                      en_IN                    en_150
 196  *                                                      en_US
 197  *  language ↓
 198  *  en              English     en          en          en          en           en
 199  *  en-US           English     en          en          en_US,      en           en
 200  *                                                      en
 201  *  en-AU           English     en_AU,      en_AU,      en_AU,      en_AU,en_GB, en_AU,en_GB,
 202  *                              en_GB,en    en_GB,en    en_GB,en    en_001,en    en_001,en
 203  *  en-CA           English     en          en_CA,      en_CA,      en_001,      en_001,
 204  *                                          en          en          en           en
 205  *  en-GB           English     en_GB,      en_GB,      en_GB,      en_GB,       en_GB,
 206  *                              en          en          en          en_001,en    en_001,en
 207  *  en-IN           English     en_GB,      en_GB,      en_IN,      en_GB,       en_GB,
 208  *                              en          en          en_GB,en    en_001,en    en_001,en
 209  *  en-US           English     en          en          en_US,      en           en
 210  *                                                      en
 211  *  en-FR           English     en_GB,      en_GB,      en_GB,      en_GB,       en_150,en_GB,
 212  *                              en          en          en          en_001,en    en_001,en
 213  *  en-IL           English     en          en          en          en_001,      en_001,
 214  *                                                                  en           en
 215  *  en-001          English     en          en          en          en_001,      en_001,
 216  *                                                                  en           en
 217  *  en-150          English     en_GB,      en_GB,      en_GB,      en_GB,       en_150,en_GB,
 218  *                              en          en          en          en_001,en    en_001,en
 219  *  en-Latn         English     en          en          en          en           en
 220  *  en-Latn_US      English     en          en          en_US,*     en           en
 221  *                                                      en
 222  *  --------
 223  *  lproj sets →    list1       list2       list3       list4       list5        list6
 224  *                  Spanish     es          es          es          es           es
 225  *                              es_MX       es_419      es_419      es_ES        es_ES
 226  *                                                      es_MX       es_MX        es_419
 227  *                                                                               es_MX
 228  *  language ↓
 229  *  es              Spanish     es          es          es          es           es
 230  *  es-ES           Spanish     es          es          es          es_ES,       es_ES,
 231  *                                                                  es           es
 232  *  es-419          Spanish     es          es_419,     es_419,     es           es_419,
 233  *                                          es          es                       es
 234  *  es-MX           Spanish     es_MX,      es_419,     es_MX,      es_MX,       es_MX,
 235  *                              es          es          es_419,es   es           es_419,es
 236  *  es-AR           Spanish     es          es_419,     es_419,     es           es_419,
 237  *                                          es          es                       es
 238  *  --------
 239  *  lproj sets →    list1       list2       list3       list4       list5        list6
 240  *                  Portuguese  pt          pt          pt
 241  *                              pt_PT       pt_BR       pt_BR
 242  *                                          pt_PT
 243  *  language ↓
 244  *  pt              Portuguese  pt          pt          pt
 245  *  pt-BR           Portuguese  pt          pt_BR,      pt_BR,
 246  *                                          pt          pt
 247  *  pt-PT           Portuguese  pt_PT,      pt_PT,      pt
 248  *                              pt          pt
 249  *  pt-MO           Portuguese  pt_PT,      pt_PT,      pt
 250  *                              pt          pt
 251  * =========================
 252  *
 253  * @param preferredLanguages
 254  *          Ordered array of pointers to user's preferred language
 255  *          codes (BCP47 style null-terminated ASCII strings), in
 256  *          order from most preferred; intended to accept the
 257  *          contents of AppleLanguages. Must not be NULL.
 258  *          Entries with the following values will be ignored:
 259  *          NULL, "", "root", any entry beginning with '-' or '_'.
 260  * @param preferredLanguagesCount
 261  *          Count of entries in preferredLanguages.
 262  * @param availableLocalizations
 263  *          Unordered array of pointers to identifiers for available
 264  *          localizations (lprojs); handles old Apple-style
 265  *          identifiers such as "English", as well as currently-
 266  *          superseded identifiers such as "no", "tl". Must not be
 267  *          NULL. Entries with the following values will be ignored:
 268  *          NULL, "", "root", any entry beginning with '-' or '_'.
 269  * @param availableLocalizationsCount
 270  *          Count of entries in availableLocalizations.
 271  * @param localizationsToUse
 272  *          Caller-provided array to be filled with pointers to
 273  *          localizations to use in the availableLocalizations
 274  *          array; these are entries from availableLocalizations
 275  *          that correspond to the first language in
 276  *          preferredLanguages for which there is any entry in
 277  *          availableLocalizations that is a reasonable match,
 278  *          with the best-matching localization first in
 279  *          localizationsToUse, followed by any other possible
 280  *          fallback localizations (for example, "en_IN" in
 281  *          preferredLanguages might produce { "en_GB, "en" } in
 282  *          localizationsToUse). Must not be NULL. This need not
 283  *          large enough to accomodate all of the localizations
 284  *          that might be returned; it is perfectly reasonable
 285  *          (and more efficient) to only provide an array with
 286  *          one entry, if that is all that you are planning to use.
 287  * @param localizationsToUseCapacity
 288  *          The capacity of localizationsToUse.
 289  * @param status
 290  *          A pointer to a UErrorCode to receive any errors.
 291  * @return
 292  *          The number of entries filled out in localizationsToUse.
 293  * @draft ICU 55
 294   */
 295 U_DRAFT int32_t U_EXPORT2
 296 ualoc_localizationsToUse( const char* const *preferredLanguages,
 297                           int32_t preferredLanguagesCount,
 298                           const char* const *availableLocalizations,
 299                           int32_t availableLocalizationsCount,
 300                           const char* *localizationsToUse,
 301                           int32_t localizationsToUseCapacity,
 302                           UErrorCode *status );
 303
 304 #endif /* U_HIDE_DRAFT_API */
 305 #endif /*UALOC_H*/