* \#include <utils_i18n.h>
*
* @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_OVERVIEW Overview
- * @details A Locale represents a specific geographical, political, or cultural region.
- * An operation that requires a Locale to perform its task is called locale-sensitive
+ * @details An operation that requires a Locale to perform its task is called locale-sensitive
* and uses the Locale to tailor information for the user. For example, displaying
* a number is a locale-sensitive operation. The number should be formatted according
* to the customs/conventions of the user's native country, region, or culture.
- * In the C APIs, a locale is simply a const char string.
+ * A locale is simply a const char string.\n
+ * You create a Locale with one of the three options listed below. Each of the component is
+ * separated by '_' in the locale string.
+ * <code>
+ * newLanguage
+ * newLanguage + newCountry
+ * newLanguage + newCountry + newVariant
+ * </code>
+ * The first option is a valid ISO Language Code. These codes are the lower-case two-letter
+ * codes as defined by ISO-639.
+ * The second option includes an additional ISO Country Code. These codes are the
+ * upper-case two-letter codes as defined by ISO-3166. You can find a full list of these
+ * codes at a number of sites, such as: http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
+ * The third option requires another additional information–the Variant. The Variant codes
+ * are vendor and browser-specific. For example, use WIN for Windows, MAC for Macintosh,
+ * and POSIX for POSIX. Where there are two variants, separate them with an underscore,
+ * and put the most important one first. For example, a Traditional Spanish collation
+ * might be referenced, with "ES", "ES", "Traditional_WIN".
+ * Because a Locale is just an identifier for a region, no validity check is performed
+ * when you specify a Locale. If you want to see whether particular resources are available
+ * for the Locale you asked for, you must query those resources. For example,
+ * to create #i18n_ucollator_h object use i18n_ucollator_get_available() function for
+ * supported locales. Note: When you ask for a resource for a particular locale,
+ * you get back the best available match, not necessarily precisely what you asked for.\n
+ * The Locale provides a number of convenient constants that you can use to specify the
+ * commonly used locales. For example, the following refers to a locale for the United States:
+ * <code>#I18N_ULOCALE_US</code>\n
+ * Once you've specified a locale you can query it for information about itself.
+ * Use i18n_ulocale_get_country() to get the ISO Country Code and i18n_ulocale_get_language()
+ * to get the ISO Language Code. You can use i18n_ulocale_get_display_country() to get
+ * the name of the country suitable for displaying to the user. Similarly, you can use
+ * i18n_ulocale_get_display_language() to get the name of the language suitable for
+ * displaying to the user. Interestingly, the i18n_ulocale_get_display_xxx() methods are
+ * themselves locale-sensitive and have two versions: one that uses the default locale
+ * and one that takes a locale as an argument and displays the name or country in a language
+ * appropriate to that locale.\n
+ * The ICU provides a number of services that perform locale-sensitive operations.
+ * For example, the i18n_unumber_xxx functions format numbers, currency, or percentages
+ * in a locale-sensitive manner. Each of these functions has two variants;
+ * one with an explicit locale and one without:\n
+ * <code>
+ * i18n_unumber_format_h num_format = NULL;
+ * int error_code = i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, "fr_FR", NULL, &num_format);
+ * </code>\n
+ * the latter using the default locale:\n
+ * <code>
+ * i18n_unumber_format_h num_format = NULL;
+ * int error_code = i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, NULL, NULL, &num_format);
+ * </code>\n
+ * A Locale is the mechanism for identifying the kind of services that you would like
+ * to get. The locale is just a mechanism for identifying these services.\n
+ * Each international service that performs locale-sensitive operations allows you to get
+ * all the available objects of that type. You can sift through these objects by language,
+ * country, or variant, and use the display names to present a menu to the user.
+ * For example, you can create a menu of all the collation objects suitable for a given
+ * language. Such modules implement these two functions: i18n_xxx_get_available(),
+ * i18n_xxx_count_available(). Some of them has also i18n_xxx_get_display_name().\n
+ * Concerning POSIX/RFC1766 Locale IDs, the
+ * i18n_locale_get_language()/i18n_ulocale_get_country()/i18n_ulocale_get_variant()/i18n_ulocale_get_name()
+ * functions do understand the POSIX type form of language_COUNTRY.ENCODING@VARIANT and
+ * if there is not an ICU-stype variant, i18n_ulocale_get_variant() for example will return
+ * the one listed after the @at sign. As well, the hyphen "-" is recognized as
+ * a country/variant separator similarly to RFC1766. So for example, "en-us" will be
+ * interpreted as en_US. As a result, i18n_ulocale_get_name() is far from a no-op,
+ * and will have the effect of converting POSIX/RFC1766 IDs into ICU form, although it
+ * does NOT map any of the actual codes (i.e. russian->ru) in any way. Applications should
+ * call i18n_ulocale_get_name() at the point where a locale ID is coming from an external
+ * source (user entry, OS, web browser) and pass the resulting string to other ICU
+ * functions. For example, don't use de-de@EURO as an argument to resourcebundle.
*
* @section CAPI_BASE_UTILS_I18N_ULOCALE_MODULE_SAMPLE_CODE_1 Sample Code 1
* @brief Gets a default locale and a full name for the locale
projects / platform / core / api / base-utils.git / commitdiff