Tizen Native API  5.5
Functions | Defines
Ulocale
i18n

A Locale represents a specific geographical, political, or cultural region.

Required Header

#include <utils_i18n.h>

Overview

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. A locale is simply a const char string.
You create a Locale with one of the three options listed below. Each of the component is separated by '_' in the locale string. newLanguage newLanguage + newCountry newLanguage + newCountry + newVariant 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.
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: I18N_ULOCALE_US
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.
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:
i18n_unumber_format_h num_format = NULL; int error_code = i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, "fr_FR", NULL, &num_format);
the latter using the default locale:
i18n_unumber_format_h num_format = NULL; int error_code = i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, NULL, NULL, &num_format);
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.
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().
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.

Sample Code 1

Gets a default locale and a full name for the locale 

    const char *locale;
    const char *in_locale_id = "en_US";
    char language[64] = {0,};
    i18n_uchar result_w[64] = {0,};
    char result[64] = {0,};
    int language_capacity = 64;
    int buf_size_language;
    int buf_size_display_name;
    int ret = I18N_ERROR_NONE;

    // Sets default locale
    ret = i18n_ulocale_set_default(getenv("LC_TIME"));

    // Gets default locale
    ret = i18n_ulocale_get_default(&locale);
    if (ret != I18N_ERROR_NONE) {
        dlog_print(DLOG_ERROR, LOG_TAG, "i18n_ulocale_get_default() failed!!! \n");
    }
    dlog_print(DLOG_INFO, LOG_TAG, "default locale : %s\n", locale);    // default locale : en_GB.UTF-8

    // Gets the language code for the specified locale
    ret = i18n_ulocale_get_language(locale, language, language_capacity, &buf_size_language);
    if (ret != I18N_ERROR_NONE) {
        dlog_print(DLOG_ERROR, LOG_TAG, "i18n_ulocale_get_language() failed!!! \n");
    }
    dlog_print(DLOG_INFO, LOG_TAG, "language code for the locale : %s\n", language);  // language code for the locale : en

    // Gets the full name suitable for display for the specified locale
    ret = i18n_ulocale_get_display_name(locale, in_locale_id, result_w, 64, &buf_size_display_name);
    if (ret != I18N_ERROR_NONE) {
        dlog_print(DLOG_ERROR, LOG_TAG, "i18n_ulocale_get_display_name() failed!!! \n");
    }
    i18n_ustring_copy_au(result, result_w);
    dlog_print(DLOG_INFO, LOG_TAG, "full name suitable for the locale : %s\n", result); // full name suitable for the locale : English (United Kingdom)

Sample Code 2

See all available locales 

    int i = 0;
    int32_t count = i18n_ulocale_count_available();
    for(i = 0; i < count; i++)
    {
        dlog_print(DLOG_INFO, LOG_TAG, "Available locale %d : %s " ,i, i18n_ulocale_get_available(i));
        //   ...
        //Available locale 5 : en_GB
        //Available locale 6 : en_US
        //Available locale 7 : en_US_POSIX
        //   ...
    }

Functions

int i18n_ulocale_get_default (const char **locale)
 Gets I18N's default locale.
int i18n_ulocale_set_default (const char *locale_id)
 Sets I18N's default locale.
int i18n_ulocale_get_language (const char *locale_id, char *language, int32_t language_capacity, int32_t *buf_size_language)
 Gets the language code for the specified locale.
int32_t i18n_ulocale_get_country (const char *locale_id, char *country, int32_t country_capacity, int *error)
 Gets the country code for the specified locale.
int i18n_ulocale_get_display_name (const char *locale_id, const char *in_locale_id, i18n_uchar *result, int32_t max_result_size, int32_t *buf_size_display_name)
 Gets the full name suitable for display for the specified locale.
const char * i18n_ulocale_get_available (int32_t n)
 Gets the specified locale from a list of all available locales.
int32_t i18n_ulocale_count_available (void)
 Gets the size of the all available locale list.
int32_t i18n_ulocale_get_script (const char *locale_id, char *script, int32_t script_capacity)
 Gets the script code for the specified locale.
int32_t i18n_ulocale_get_variant (const char *locale_id, char *variant, int32_t variant_capacity)
 Gets the variant code for the specified locale.
int32_t i18n_ulocale_get_name (const char *locale_id, char *name, int32_t name_capacity)
 Gets the full name for the specified locale.
int32_t i18n_ulocale_canonicalize (const char *locale_id, char *name, int32_t name_capacity)
 Gets the full name for the specified locale.
const char * i18n_ulocale_get_iso3_language (const char *locale_id)
 Gets the ISO language code for the specified locale.
const char * i18n_ulocale_get_iso3_country (const char *locale_id)
 Gets the ISO country code for the specified locale.
uint32_t i18n_ulocale_get_lcid (const char *locale_id)
 Gets the Win32 LCID value for the specified locale.
int32_t i18n_ulocale_get_display_language (const char *locale, const char *display_locale, i18n_uchar *language, int32_t language_capacity)
 Gets the language name suitable for display for the specified locale.
int32_t i18n_ulocale_get_display_script (const char *locale, const char *display_locale, i18n_uchar *script, int32_t script_capacity)
 Gets the script name suitable for display for the specified locale.
int32_t i18n_ulocale_get_display_country (const char *locale, const char *display_locale, i18n_uchar *country, int32_t country_capacity)
 Gets the country name suitable for display for the specified locale.
int32_t i18n_ulocale_get_display_variant (const char *locale, const char *display_locale, i18n_uchar *variant, int32_t variant_capacity)
 Gets the variant name suitable for display for the specified locale.
int32_t i18n_ulocale_get_display_keyword (const char *keyword, const char *display_locale, i18n_uchar *dest, int32_t dest_capacity)
 Gets the keyword name suitable for display for the specified locale.
int32_t i18n_ulocale_get_display_keyword_value (const char *locale, const char *keyword, const char *display_locale, i18n_uchar *dest, int32_t dest_capacity)
 Gets the value of the keyword suitable for display for the specified locale.
const char *const * i18n_ulocale_get_iso_languages (void)
 Gets a list of all available 2-letter language codes defined in ISO 639, plus additional 3-letter codes determined to be useful for locale generation as defined by Unicode CLDR.
const char *const * i18n_ulocale_get_iso_countries (void)
 Gets a list of all available 2-letter country codes defined in ISO 639.
int32_t i18n_ulocale_get_parent (const char *locale_id, char *parent, int32_t parent_capacity)
 Truncates the locale ID string to get the parent locale ID.
int32_t i18n_ulocale_get_base_name (const char *locale_id, char *name, int32_t name_capacity)
 Gets the full name for the specified locale, like i18n_ulocale_get_name(), but without keywords.
int i18n_ulocale_keywords_create (const char *locale_id, i18n_uenumeration_h *enumeration)
 Gets an enumeration of keywords for the specified locale.
int32_t i18n_ulocale_get_keyword_value (const char *locale_id, const char *keyword_name, char *buffer, int32_t buffer_capacity)
 Gets the value for a keyword.
int32_t i18n_ulocale_set_keyword_value (const char *keyword_name, const char *keyword_value, char *buffer, int32_t buffer_capacity)
 Sets or removes the value of the specified keyword.
int i18n_ulocale_get_character_orientation (const char *locale_id, i18n_ulocale_layout_type_e *layout_type)
 Gets the layout character orientation for the specified locale.
int i18n_ulocale_get_line_orientation (const char *locale_id, i18n_ulocale_layout_type_e *layout_type)
 Gets the layout line orientation for the specified locale.
int32_t i18n_ulocale_get_locale_for_lcid (uint32_t host_id, char *locale, int32_t locale_capacity)
 Gets the I18N locale ID for the specified Win32 LCID value.
int32_t i18n_ulocale_add_likely_subtags (const char *locale_id, char *maximized_locale_id, int32_t maximized_locale_id_capacity)
 Adds the likely subtags for a provided locale ID, per the algorithm described in the following CLDR technical report : http://www.unicode.org/reports/tr35/#Likely_Subtags.
int32_t i18n_ulocale_minimize_subtags (const char *locale_id, char *minimized_locale_id, int32_t minimized_locale_id_capacity)
 Minimizes the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags.
int32_t i18n_ulocale_for_language_tag (const char *langtag, char *locale_id, int32_t locale_id_capacity, int32_t *parsed_length)
 Returns a locale ID for the specified BCP47 language tag string.
int32_t i18n_ulocale_to_language_tag (const char *locale_id, char *langtag, int32_t langtag_capacity, i18n_ubool strict)
 Returns a well-formed language tag for this locale ID.
int i18n_ulocale_is_bogus (const char *locale_id, i18n_ubool *is_bogus)
 Gets the bogus state.

Defines

#define I18N_ULOCALE_CHINESE   "zh"
#define I18N_ULOCALE_ENGLISH   "en"
#define I18N_ULOCALE_FRENCH   "fr"
#define I18N_ULOCALE_GERMAN   "de"
#define I18N_ULOCALE_ITALIAN   "it"
#define I18N_ULOCALE_JAPANESE   "ja"
#define I18N_ULOCALE_KOREAN   "ko"
#define I18N_ULOCALE_SIMPLIFIED_CHINESE   "zh_CN"
#define I18N_ULOCALE_TRADITIONAL_CHINESE   "zh_TW"
#define I18N_ULOCALE_CANADA   "en_CA"
#define I18N_ULOCALE_CANADA_FRENCH   "fr_CA"
#define I18N_ULOCALE_CHINA   "zh_CN"
#define I18N_ULOCALE_PRC   "zh_CN"
#define I18N_ULOCALE_FRANCE   "fr_FR"
#define I18N_ULOCALE_GERMANY   "de_DE"
#define I18N_ULOCALE_ITALY   "it_IT"
#define I18N_ULOCALE_JAPAN   "ja_JP"
#define I18N_ULOCALE_KOREA   "ko_KR"
#define I18N_ULOCALE_TAIWAN   "zh_TW"
#define I18N_ULOCALE_UK   "en_GB"
#define I18N_ULOCALE_US   "en_US"
#define I18N_ULOCALE_LANG_CAPACITY   12
 Useful constant for the maximum size of the language part of a locale ID. (including the terminating NULL).
#define I18N_ULOCALE_COUNTRY_CAPACITY   4
 Useful constant for the maximum size of the country part of a locale ID (including the terminating NULL).
#define I18N_ULOCALE_FULLNAME_CAPACITY   157
 Useful constant for the maximum size of the whole locale ID (including the terminating NULL and all keywords).
#define I18N_ULOCALE_SCRIPT_CAPACITY   6
 Useful constant for the maximum size of the script part of a locale ID (including the terminating NULL).
#define I18N_ULOCALE_KEYWORDS_CAPACITY   96
 Useful constant for the maximum size of keywords in a locale.
#define I18N_ULOCALE_KEYWORD_AND_VALUES_CAPACITY   100
 Useful constant for the maximum total size of keywords and their values in a locale.
#define I18N_ULOCALE_KEYWORD_SEPARATOR   '@'
 Invariant character separating keywords from the locale string.
#define I18N_ULOCALE_KEYWORD_SEPARATOR_UNICODE   0x40
 Unicode code point for '@' separating keywords from the locale string.
#define I18N_ULOCALE_KEYWORD_ASSIGN   '='
 Invariant character for assigning value to a keyword.
#define I18N_ULOCALE_KEYWORD_ASSIGN_UNICODE   0x3D
 Unicode code point for '=' for assigning value to a keyword.
#define I18N_ULOCALE_KEYWORD_ITEM_SEPARATOR   ';'
 Invariant character separating keywords.
#define I18N_ULOCALE_KEYWORD_ITEM_SEPARATOR_UNICODE   0x3B
 Unicode code point for ';' separating keywords.

Define Documentation

#define I18N_ULOCALE_CANADA   "en_CA"

Useful constant for en_CA.

Since :
2.3.1
#define I18N_ULOCALE_CANADA_FRENCH   "fr_CA"

Useful constant for fr_CA.

Since :
2.3.1
#define I18N_ULOCALE_CHINA   "zh_CN"

Useful constant for zh_CN.

Since :
2.3.1
#define I18N_ULOCALE_CHINESE   "zh"

Useful constant for zh.

Since :
2.3.1
#define I18N_ULOCALE_COUNTRY_CAPACITY   4

Useful constant for the maximum size of the country part of a locale ID (including the terminating NULL).

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
i18n_ulocale_get_country()
#define I18N_ULOCALE_ENGLISH   "en"

Useful constant for en.

Since :
2.3.1
#define I18N_ULOCALE_FRANCE   "fr_FR"

Useful constant for fr_FR.

Since :
2.3.1
#define I18N_ULOCALE_FRENCH   "fr"

Useful constant for fr.

Since :
2.3.1
#define I18N_ULOCALE_FULLNAME_CAPACITY   157

Useful constant for the maximum size of the whole locale ID (including the terminating NULL and all keywords).

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_GERMAN   "de"

Useful constant for de.

Since :
2.3.1
#define I18N_ULOCALE_GERMANY   "de_DE"

Useful constant for de_DE.

Since :
2.3.1
#define I18N_ULOCALE_ITALIAN   "it"

Useful constant for it.

Since :
2.3.1
#define I18N_ULOCALE_ITALY   "it_IT"

Useful constant for it_IT.

Since :
2.3.1
#define I18N_ULOCALE_JAPAN   "ja_JP"

Useful constant for ja_JP.

Since :
2.3.1
#define I18N_ULOCALE_JAPANESE   "ja"

Useful constant for ja.

Since :
2.3.1
#define I18N_ULOCALE_KEYWORD_AND_VALUES_CAPACITY   100

Useful constant for the maximum total size of keywords and their values in a locale.

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KEYWORD_ASSIGN   '='

Invariant character for assigning value to a keyword.

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KEYWORD_ASSIGN_UNICODE   0x3D

Unicode code point for '=' for assigning value to a keyword.

Since :
3.0
See also:
I18N_ULOCALE_KEYWORD_ASSIGN
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KEYWORD_ITEM_SEPARATOR   ';'

Invariant character separating keywords.

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KEYWORD_ITEM_SEPARATOR_UNICODE   0x3B

Unicode code point for ';' separating keywords.

Since :
3.0
See also:
I18N_ULOCALE_KEYWORD_ITEM_SEPARATOR
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KEYWORD_SEPARATOR   '@'

Invariant character separating keywords from the locale string.

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KEYWORD_SEPARATOR_UNICODE   0x40

Unicode code point for '@' separating keywords from the locale string.

Since :
3.0
See also:
I18N_ULOCALE_KEYWORD_SEPARATOR
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KEYWORDS_CAPACITY   96

Useful constant for the maximum size of keywords in a locale.

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
#define I18N_ULOCALE_KOREA   "ko_KR"

Useful constant for ko_KR.

Since :
2.3.1
#define I18N_ULOCALE_KOREAN   "ko"

Useful constant for ko.

Since :
2.3.1
#define I18N_ULOCALE_LANG_CAPACITY   12

Useful constant for the maximum size of the language part of a locale ID. (including the terminating NULL).

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
i18n_ulocale_get_language()
#define I18N_ULOCALE_PRC   "zh_CN"

Useful constant for zh_CN.

Since :
2.3.1
#define I18N_ULOCALE_SCRIPT_CAPACITY   6

Useful constant for the maximum size of the script part of a locale ID (including the terminating NULL).

Since :
3.0
See also:
i18n_ulocale_get_keyword_value()
i18n_ulocale_get_script()
#define I18N_ULOCALE_SIMPLIFIED_CHINESE   "zh_CN"

Useful constant for zh_CN.

Since :
2.3.1
#define I18N_ULOCALE_TAIWAN   "zh_TW"

Useful constant for zh_TW.

Since :
2.3.1
#define I18N_ULOCALE_TRADITIONAL_CHINESE   "zh_TW"

Useful constant for zh_TW.

Since :
2.3.1
#define I18N_ULOCALE_UK   "en_GB"

Useful constant for en_GB.

Since :
2.3.1
#define I18N_ULOCALE_US   "en_US"

Useful constant for en_US.

Since :
2.3.1

Enumeration Type Documentation

enum i18n_ulocale_accept_result_e

Enumeration for the 'out_result' parameter return value.

Since :
2.3.1
See also:
i18n_ulocale_accept_language_from_http()
i18n_ulocale_accept_language()
Enumerator:
I18N_ULOCALE_ACCEPT_FAILED 

No exact match was found

I18N_ULOCALE_ACCEPT_VALID 

An exact match was found

I18N_ULOCALE_ACCEPT_FALLBACK 

A fallback was found, for example, accept list contained 'ja_JP' which matched available locale 'ja'

enum i18n_ulocale_data_locale_type_e

Enumeration for data locale types.

Since :
2.3.1
Enumerator:
I18N_ULOCALE_DATA_LOCALE_TYPE_ACTUAL_LOCALE 

Actual locale

I18N_ULOCALE_DATA_LOCALE_TYPE_VALID_LOCALE 

Valid locale

I18N_ULOCALE_DATA_LOCALE_TYPE_LIMIT 

Locale type limit

enum i18n_ulocale_layout_type_e

Enumeration for the return value for the character and line orientation functions.

Since :
2.3.1
Enumerator:
I18N_ULOCALE_LAYOUT_LTR 

Left-to-right

I18N_ULOCALE_LAYOUT_RTL 

Right-to-left

I18N_ULOCALE_LAYOUT_TTB 

Top-to-bottom

I18N_ULOCALE_LAYOUT_BTT 

Bottom-to-top

I18N_ULOCALE_LAYOUT_UNKNOWN 

Unknown

Function Documentation

int32_t i18n_ulocale_add_likely_subtags ( const char *  locale_id,
char *  maximized_locale_id,
int32_t  maximized_locale_id_capacity 
)

Adds the likely subtags for a provided locale ID, per the algorithm described in the following CLDR technical report : http://www.unicode.org/reports/tr35/#Likely_Subtags.

If locale_id is already in the maximal form, or there is no data available for maximization, it will be copied to the output buffer. For example, "und-Zzzz" cannot be maximized, since there is no reasonable maximization.

Examples :

"en" maximizes to "en_Latn_US"

"de" maximizes to "de_Latn_US"

"sr" maximizes to "sr_Cyrl_RS"

"sh" maximizes to "sr_Latn_RS" (Note this will not reverse.)

"zh_Hani" maximizes to "zh_Hans_CN" (Note this will not reverse.)

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to maximize
[out]maximized_locale_idThe maximized locale
[in]maximized_locale_id_capacityThe capacity of the maximized_locale_id buffer
Returns:
The actual buffer size needed for the maximized locale. If it's greater than maximized_lacale_id_capacity, the returned ID will be truncated. On error, the return value is -1.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_canonicalize ( const char *  locale_id,
char *  name,
int32_t  name_capacity 
)

Gets the full name for the specified locale.

Note : This has the effect of 'canonicalizing' the string to a certain extent. Upper and lower case are set as needed, and if the components were in 'POSIX' format they are changed to I18N format. It does NOT map aliased names in any way. See the top of this header file.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the full name with
[out]nameThe full name for locale_id
[in]name_capacityThe size of the name buffer to store the full name with
Returns:
The actual buffer size needed for the full name. If it's greater than name_capacity, the returned full name will be truncated.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_BUFFER_OVERFLOWA result would not fit in the supplied buffer
int32_t i18n_ulocale_count_available ( void  )

Gets the size of the all available locale list.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Returns:
The size of the locale list
Exceptions:
I18N_ERROR_NONESuccess
int32_t i18n_ulocale_for_language_tag ( const char *  langtag,
char *  locale_id,
int32_t  locale_id_capacity,
int32_t *  parsed_length 
)

Returns a locale ID for the specified BCP47 language tag string.

If the specified language tag contains any ill-formed subtags, the first such subtag and all following subtags are ignored.

This implements the 'Language-Tag' production of BCP47, and so supports grandfathered (regular and irregular) as well as private use language tags. Private use tags are represented as 'x-whatever', and grandfathered tags are converted to their canonical replacements where they exist. Note that a few grandfathered tags have no modern replacement, these will be converted using the fallback described in the first paragraph, so some information might be lost.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]langtagThe input BCP47 language tag.
[out]locale_idThe output buffer receiving a locale ID for the specified BCP47 language tag.
[in]locale_id_capacityThe size of the locale_id output buffer.
[in]parsed_lengthIf not NULL, successfully parsed length for the input language tag is set.
Returns:
The length of the locale ID. If the langtag or locale_id buffer is NULL or the locale_id_capacity is lower than 0, then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
const char* i18n_ulocale_get_available ( int32_t  n)

Gets the specified locale from a list of all available locales.

The return value is a pointer to an item of a locale name array. Both this array and the pointers it contains are owned by I18N and should not be deleted or written through by the caller. The locale name is terminated by a null pointer.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]nThe specific locale name index of the available locale list
Returns:
A specified locale name of all available locales
Exceptions:
I18N_ERROR_NONESuccess
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_base_name ( const char *  locale_id,
char *  name,
int32_t  name_capacity 
)

Gets the full name for the specified locale, like i18n_ulocale_get_name(), but without keywords.

Note : This has the effect of 'canonicalizing' the string to a certain extent. Upper and lower case are set as needed, and if the components were in 'POSIX' format they are changed to I18N format. It does NOT map aliased names in any way. See the top of this header file.

This API strips off the keyword part, so "de_DE\@collation=phonebook" will become "de_DE". This API supports preflighting.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the full name with
[out]nameFill in buffer for the name without keywords.
[in]name_capacityCapacity of the fill in buffer.
Returns:
The actual buffer size needed for the full name. If it's greater than name_capacity, the returned full name will be truncated.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_BUFFER_OVERFLOWA result would not fit in the supplied buffer
int i18n_ulocale_get_character_orientation ( const char *  locale_id,
i18n_ulocale_layout_type_e *  layout_type 
)

Gets the layout character orientation for the specified locale.

Remarks:
Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idlocale name
[out]layout_typeA pointer to the enum indicating the layout orientation for characters.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_country ( const char *  locale_id,
char *  country,
int32_t  country_capacity,
int *  error 
)

Gets the country code for the specified locale.

Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the country code with
[out]countryThe country code for locale_id
[in]country_capacityThe size of the country buffer to store the country code with
[out]errorError information if retrieving the country code failed
Returns:
The actual buffer size needed for the country code.
If it's greater than country_capacity, the returned country code will be truncated.
int i18n_ulocale_get_default ( const char **  locale)

Gets I18N's default locale.

The returned string is a snapshot in time, and will remain valid and unchanged even when i18n_ulocale_set_default() is called. The returned storage is owned by I18N, and must not be altered or deleted by the caller.

Since :
2.3.1
Parameters:
[out]localeThe I18N default locale
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_display_country ( const char *  locale,
const char *  display_locale,
i18n_uchar *  country,
int32_t  country_capacity 
)

Gets the country name suitable for display for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]localeThe locale to get the displayable country code with. NULL may be used to specify the default.
[in]display_localeThe locale to be used to display the name. NULL may be used to specify the default.
[out]countryThe displayable country code for locale
[in]country_capacityThe size of the country buffer to store the displayable country code with
Returns:
The actual buffer size needed for the displayable country code. If it's greater than country_capacity, the returned displayable country code will be truncated. If the country buffer is NULL or the country_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and 0 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_display_keyword ( const char *  keyword,
const char *  display_locale,
i18n_uchar *  dest,
int32_t  dest_capacity 
)

Gets the keyword name suitable for display for the specified locale.

E.g : for the locale string de_DE@collation=PHONEBOOK, this API gets the display string for the keyword collation. Usage : 

      i18n_error_code_e status = I18N_ERROR_NONE;
      const char* keyword = NULL;
      int32_t keyword_len = 0;
      int32_t keyword_count = 0;
      i18n_uchar display_keyword[256];
      int32_t display_keyword_len = 0;
      i18n_uenumeration_h keyword_enum;
      i18n_ulocale_keywords_create("en_US@collation=PHONEBOOK;calendar=TRADITIONAL", &keyword_enum);

      for(keyword_count = i18n_uenumeration_count(keyword_enum); keyword_count > 0; keyword_count--){
            status = get_last_result();
            if(status > 0){
                // something went wrong so handle the error
                break;
            }
            // the uenum_next returns NULL-terminated string
            keyword = i18n_uenumeration_next(keyword_enum, &keyword_len);
            display_keyword_len = i18n_ulocale_get_display_keyword(keyword, "en_US", display_keyword, 256);
            // do something interesting
      }
      i18n_uenumeration_destroy(keyword_enum);
Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]keywordThe keyword whose display string needs to be returned.
[in]display_localeThe locale to be used to display the name. NULL may be used to specify the default.
[out]destThe buffer to which the displayable keyword should be written.
[in]dest_capacityThe size of the buffer (number of i18n_uchar characters). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
Returns:
The actual buffer size needed for the displayable variant code. If the dest buffer is NULL or the dest_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and 0 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_ulocale_keywords_create()
i18n_uenumeration_count()
i18n_uenumeration_next()
i18n_uenumeration_destroy()
int32_t i18n_ulocale_get_display_keyword_value ( const char *  locale,
const char *  keyword,
const char *  display_locale,
i18n_uchar *  dest,
int32_t  dest_capacity 
)

Gets the value of the keyword suitable for display for the specified locale.

E.g : for the locale string de_DE@collation=PHONEBOOK, this API gets the display string for PHONEBOOK, in the display locale, when "collation" is specified as the keyword.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]localeThe locale to get the displayable variant code with. NULL may be used to specify the default.
[in]keywordThe keyword for whose value should be used.
[in]display_localeThe locale to be used to display the name. NULL may be used to specify the default.
[out]destThe buffer to which the displayable keyword should be written.
[in]dest_capacityThe size of the buffer (number of i18n_uchar characters). If it is 0, then dest may be NULL and the function will only return the length of the result without writing any of the result string (pre-flighting).
Returns:
The actual buffer size needed for the displayable variant code. If the dest buffer is NULL or the dest_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and 0 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_display_language ( const char *  locale,
const char *  display_locale,
i18n_uchar *  language,
int32_t  language_capacity 
)

Gets the language name suitable for display for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]localeThe locale to get the ISO language code with
[in]display_localeThe locale to be used to display the name.
NULL may be used to specify the default.
[out]languageThe displayable language code for locale.
[in]language_capacityThe size of the language buffer to store the displayable language code with
Returns:
The actual buffer size needed for the displayable language code. If it's greater than language_capacity, the returned language code will be truncated. If the language buffer is NULL or the language_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and 0 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ulocale_get_display_name ( const char *  locale_id,
const char *  in_locale_id,
i18n_uchar *  result,
int32_t  max_result_size,
int32_t *  buf_size_display_name 
)

Gets the full name suitable for display for the specified locale.

Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the displayable name with.
NULL may be used to specify the default.
[in]in_locale_idThe locale to be used to display the name.
NULL may be used to specify the default.
[out]resultThe displayable name for locale_id
[in]max_result_sizeThe size of the name buffer to store the displayable full name with
[out]buf_size_display_nameThe actual buffer size needed for the displayable name.
If it's greater than max_result_size, the returned displayable name will be truncated.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_display_script ( const char *  locale,
const char *  display_locale,
i18n_uchar *  script,
int32_t  script_capacity 
)

Gets the script name suitable for display for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]localeThe locale to get the displayable script code with. NULL may be used to specify the default.
[in]display_localeThe locale to be used to display the name. NULL may be used to specify the default.
[out]scriptThe displayable country code for locale
[in]script_capacityThe size of the script buffer to store the displayable script code with
Returns:
The actual buffer size needed for the displayable script code. If it's greater than script_capacity, the returned displayable script code will be truncated. If the script buffer is NULL or the script_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and 0 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_display_variant ( const char *  locale,
const char *  display_locale,
i18n_uchar *  variant,
int32_t  variant_capacity 
)

Gets the variant name suitable for display for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]localeThe locale to get the displayable variant code with. NULL may be used to specify the default.
[in]display_localeThe locale to be used to display the name. NULL may be used to specify the default.
[out]variantThe displayable variant code for locale
[in]variant_capacityThe size of the variant buffer to store the displayable variant code with
Returns:
The actual buffer size needed for the displayable variant code. If it's greater than variant_capacity, the returned displayable variant code will be truncated. If the variant buffer is NULL or the variant_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and 0 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
const char* i18n_ulocale_get_iso3_country ( const char *  locale_id)

Gets the ISO country code for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the ISO country code with
Returns:
A country the ISO country code for locale_id
Exceptions:
I18N_ERROR_NONESuccessful
const char* i18n_ulocale_get_iso3_language ( const char *  locale_id)

Gets the ISO language code for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the ISO language code with
Returns:
A language the ISO language code for locale_id
Exceptions:
I18N_ERROR_NONESuccessful
const char* const* i18n_ulocale_get_iso_countries ( void  )

Gets a list of all available 2-letter country codes defined in ISO 639.

This is a pointer to an array of pointers to arrays of char. All of these pointers are owned by I18N - do not delete them, and do not write through them. The array is terminated with a NULL pointer.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Returns:
A list of all available country codes
Exceptions:
I18N_ERROR_NONESuccessful
const char* const* i18n_ulocale_get_iso_languages ( void  )

Gets a list of all available 2-letter language codes defined in ISO 639, plus additional 3-letter codes determined to be useful for locale generation as defined by Unicode CLDR.

This is a pointer to an array of pointers to arrays of char. All of these pointers are owned by I18N - do not delete them, and do not write through them. The array is terminated with a NULL pointer.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Returns:
A list of all available language codes
Exceptions:
I18N_ERROR_NONESuccessful
int32_t i18n_ulocale_get_keyword_value ( const char *  locale_id,
const char *  keyword_name,
char *  buffer,
int32_t  buffer_capacity 
)

Gets the value for a keyword.

Locale name does not need to be normalized.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idA locale name containing the keyword ("de_DE@currency=EURO;collation=PHONEBOOK")
[in]keyword_nameThe name of the keyword for which we want the value. Case insensitive.
[out]bufferReceiving buffer
[in]buffer_capacityCapacity of receiving buffer
Returns:
The length of keyword value. If the keyword_name or buffer is NULL or the buffer_capacity is lower than 0, then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ulocale_get_language ( const char *  locale_id,
char *  language,
int32_t  language_capacity,
int32_t *  buf_size_language 
)

Gets the language code for the specified locale.

Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the ISO language code with.
NULL may be used to specify the default.
[out]languageThe language code for locale_id
[in]language_capacityThe size of the language buffer to store the language code with
[out]buf_size_languageThe actual buffer size needed for the language code.
If it's greater than language_capacity, the returned language code will be truncated.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
uint32_t i18n_ulocale_get_lcid ( const char *  locale_id)

Gets the Win32 LCID value for the specified locale.

If the I18N locale is not recognized by Windows, 0 will be returned.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the Win32 LCID value with
Returns:
A country the Win32 LCID for locale_id
Exceptions:
I18N_ERROR_NONESuccessful
int i18n_ulocale_get_line_orientation ( const char *  locale_id,
i18n_ulocale_layout_type_e *  layout_type 
)

Gets the layout line orientation for the specified locale.

Remarks:
Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idlocale name
[out]layout_typeA pointer to the enum indicating the layout orientation for lines.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_locale_for_lcid ( uint32_t  host_id,
char *  locale,
int32_t  locale_capacity 
)

Gets the I18N locale ID for the specified Win32 LCID value.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]host_idThe Win32 LCID to translate
[out]localeThe output buffer for the I18N locale ID, which will be NULL-terminated if there is room.
[in]locale_capacityThe size of the output buffer
Returns:
The actual size of the locale ID, not including NULL-termination. If the locale buffer is NULL or the locale_capacity is lower than 0, then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_name ( const char *  locale_id,
char *  name,
int32_t  name_capacity 
)

Gets the full name for the specified locale.

Note : This has the effect of 'canonicalizing' the I18N locale ID to a certain extent. Upper and lower case are set as needed. It does NOT map aliased names in any way. See the top of this header file. This API supports preflighting.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the full name with
[out]nameFill in buffer for the name without keywords.
[in]name_capacityCapacity of the fill in buffer.
Returns:
The actual buffer size needed for the full name. If it's greater than name_capacity, the returned full name will be truncated.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_BUFFER_OVERFLOWA result would not fit in the supplied buffer
int32_t i18n_ulocale_get_parent ( const char *  locale_id,
char *  parent,
int32_t  parent_capacity 
)

Truncates the locale ID string to get the parent locale ID.

Copies the part of the string before the last underscore. The parent locale ID will be an empty string if there is no underscore, or if there is only one underscore at locale_id[0].

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idInput locale ID string.
[out]parentOutput string buffer for the parent locale ID. Must not be NULL.
[in]parent_capacitySize of the output buffer. If it's lower than the number of characters stored in the locale_id between the first character and the last occurrence of the underscore ("_") character, than the error code will be set to I18N_ERROR_BUFFER_OVERFLOW.
Returns:
The length of the parent locale ID. If the parent buffer is NULL or the parent_capacity is lower than 0, then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWIf the capacity of the parent is lower than the number of characters in the locale_id from index 0 to the index of the last occurrence of the underscore ("_") symbol.
int32_t i18n_ulocale_get_script ( const char *  locale_id,
char *  script,
int32_t  script_capacity 
)

Gets the script code for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the ISO script code with
[out]scriptThe script code for locale_id. Must not be NULL.
[in]script_capacityThe size of the script buffer to store the script code with
Returns:
The actual buffer size needed for the script code. If it's greater than script_capacity, the returned script code will be truncated. If the script buffer is NULL or the script_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_get_variant ( const char *  locale_id,
char *  variant,
int32_t  variant_capacity 
)

Gets the variant code for the specified locale.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the variant code with
[out]variantThe variant code for locale_id
[in]variant_capacityThe size of the variant buffer to store the variant code with
Returns:
The actual buffer size needed for the variant code. If it's greater than variant_capacity, the returned variant code will be truncated. If the variant buffer is NULL or the variant_capacity is lower than 0 , then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ulocale_is_bogus ( const char *  locale_id,
i18n_ubool *  is_bogus 
)

Gets the bogus state.

A locale string can be bogus if it does not identify an existing locale.

Since :
4.0
Parameters:
[in]locale_idThe input locale ID
[out]is_bogusBoolean value indicating if the given locale is bogus.
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ulocale_keywords_create ( const char *  locale_id,
i18n_uenumeration_h *  enumeration 
)

Gets an enumeration of keywords for the specified locale.

Enumeration must get disposed of by the client using i18n_uenumeration_destroy() function.

Remarks:
Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to get the variant code with
enumerationA pointer to the enumeration of keywords or NULL if there are no keywords.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_minimize_subtags ( const char *  locale_id,
char *  minimized_locale_id,
int32_t  minimized_locale_id_capacity 
)

Minimizes the subtags for a provided locale ID, per the algorithm described in the following CLDR technical report: http://www.unicode.org/reports/tr35/#Likely_Subtags.

If locale_id is already in the minimal form, or there is no data available for minimization, it will be copied to the output buffer. Since the minimization algorithm relies on proper maximization, see the comments for i18n_ulocale_add_likely_subtags() for reasons why there might not be any data.

Examples :

"en_Latn_US" minimizes to "en"

"de_Latn_US" minimizes to "de"

"sr_Cyrl_RS" minimizes to "sr"

"zh_Hant_TW" minimizes to "zh_TW" (The region is preferred to the script, and minimizing to "zh" would imply "zh_Hans_CN".)

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe locale to minimize
[out]minimized_locale_idThe minimized locale
[in]minimized_locale_id_capacityThe capacity of the minimized_locale_id buffer
Returns:
The actual buffer size needed for the minimized locale. If it's greater than minimized_locale_id_capacity, the returned ID will be truncated. On error, the return value is -1.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int i18n_ulocale_set_default ( const char *  locale_id)

Sets I18N's default locale.

By default (without calling this function), I18N's default locale will be based on information obtained from the underlying system environment.

Changes to I18N's default locale do not propagate back to the system environment.

Changes to I18N's default locale to not affect any services that may already be open based on the previous default locale value.

Since :
2.3.1
Parameters:
[in]locale_idThe new I18N default locale.
A value of NULL will try to get the system's default locale.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
int32_t i18n_ulocale_set_keyword_value ( const char *  keyword_name,
const char *  keyword_value,
char *  buffer,
int32_t  buffer_capacity 
)

Sets or removes the value of the specified keyword.

For removing all keywords(retrieving only locale base name associated with the keywords), use i18n_ulocale_get_base_name().

NOTE : Unlike almost every other I18N function which takes a buffer, this function will NOT truncate the output text. If a I18N_ERROR_BUFFER_OVERFLOW is received, it means that the original buffer is untouched. This is done to prevent incorrect or possibly even malformed locales from being generated and used.

Below code prints following logs in SDK:

Locale and keywords: en_US@abc=12;def=34
keyword1: abc
keyword2: def
Locale: en_US
Keyword1 value: 12

      int32_t buff_size = 50;
      int32_t sub_buff_size = 45;
      char *buff = malloc(sizeof(char)*buff_size);
      char *sub_buff = malloc(sizeof(char)*sub_buff_size);
      char *locale = "en_US";

      snprintf(buff, buff_size, "%s%s",locale, sub_buff);

      i18n_ulocale_set_keyword_value("abc", "cba", buff, buff_size);
      i18n_ulocale_set_keyword_value("def", "34", buff, buff_size);

      i18n_uenumeration_h keyword_enum;
      i18n_ulocale_keywords_create(buff, &keyword_enum);

      int32_t res_len = 0;
      const char *keyw = i18n_uenumeration_next(keyword_enum, &res_len);
      const char *keyw2 = i18n_uenumeration_next(keyword_enum, &res_len);

      char *only_locale = malloc(sizeof(char)*10);
      i18n_ulocale_get_base_name(buff, only_locale, 10);

      int32_t buff_size_get = 50;
      char *buff_out = malloc(sizeof(char)*buff_size_get);
      i18n_ulocale_get_keyword_value(buff, "abc", buff_out, buff_size_get);

      dlog_print(DLOG_DEBUG, "test", "Locale and keywords: %s", buff);
      dlog_print(DLOG_DEBUG, "test", "keyword1: %s", keyw);
      dlog_print(DLOG_DEBUG, "test", "keyword2: %s", keyw2);
      dlog_print(DLOG_DEBUG, "test", "Locale: %s", only_locale);
      dlog_print(DLOG_DEBUG, "test", "Keyword1 value: %s", buff_out);

      i18n_uenumeration_destroy(keyword_enum)
      free(buff);
      free(sub_buff);
      free(only_locale);
      free(buff_out);
Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]keyword_nameA name of the keyword to be set. Case insensitive.
[in]keyword_valueA value of the keyword to be set. If 0-length or NULL, will result in the keyword being removed. No error is given if that keyword does not exist.
[out]bufferInput buffer containing locale to be modified.
[in]buffer_capacityCapacity of receiving buffer
Returns:
The length needed for the buffer. If the keyword_name or buffer is NULL or the buffer_capacity is lower than 0, then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
See also:
i18n_ulocale_get_keyword_value()
int32_t i18n_ulocale_to_language_tag ( const char *  locale_id,
char *  langtag,
int32_t  langtag_capacity,
i18n_ubool  strict 
)

Returns a well-formed language tag for this locale ID.

Note : When strict is false, any locale fields which do not satisfy the BCP47 syntax requirement will be omitted from the result. When strict is true, this function sets I18N_ERROR_INVALID_PARAMETER to the result if any locale fields do not satisfy the BCP47 syntax requirement.

Remarks:
The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.
Since :
2.3.1
Parameters:
[in]locale_idThe input locale ID
[out]langtagThe output buffer receiving BCP47 language tag for the locale ID.
[in]langtag_capacityThe size of the BCP47 language tag output buffer.
[in]strictBoolean value indicating if the function returns an error for an ill-formed input locale ID.
Returns:
The length of the BCP47 language tag. If the locale_id or langtag buffer is NULL or the langtag_capacity is lower than 0, then the I18N_ERROR_INVALID_PARAMETER error will be set and -1 will be returned.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter