Skip to content

Most visited

Recently visited

navigation

ULocale

public final class ULocale
extends Object implements Serializable, Comparable<ULocale>

java.lang.Object
   ↳ android.icu.util.ULocale


[icu enhancement] ICU's replacement for Locale. Methods, fields, and other functionality specific to ICU are labeled '[icu]'. A class analogous to Locale that provides additional support for ICU protocol. In ICU 3.0 this class is enhanced to support RFC 3066 language identifiers.

Many classes and services in ICU follow a factory idiom, in which a factory method or object responds to a client request with an object. The request includes a locale (the requested locale), and the returned object is constructed using data for that locale. The system may lack data for the requested locale, in which case the locale fallback mechanism will be invoked until a populated locale is found (the valid locale). Furthermore, even when a populated locale is found (the valid locale), further fallback may be required to reach a locale containing the specific data required by the service (the actual locale).

ULocale performs 'normalization' and 'canonicalization' of locale ids. Normalization 'cleans up' ICU locale ids as follows:

  • language, script, country, variant, and keywords are properly cased
    (lower, title, upper, upper, and lower case respectively)
  • hyphens used as separators are converted to underscores
  • three-letter language and country ids are converted to two-letter equivalents where available
  • surrounding spaces are removed from keywords and values
  • if there are multiple keywords, they are put in sorted order
Canonicalization additionally performs the following:
  • POSIX ids are converted to ICU format IDs
  • 'grandfathered' 3066 ids are converted to ICU standard form
  • 'PREEURO' and 'EURO' variants are converted to currency keyword form, with the currency id appropriate to the country of the locale (for PREEURO) or EUR (for EURO).
All ULocale constructors automatically normalize the locale id. To handle POSIX ids, canonicalize can be called to convert the id to canonical form, or the canonicalInstance factory method can be called.

Note: The actual locale is returned correctly, but the valid locale is not, in most cases.

See also:

Summary

Nested classes

class ULocale.Builder

Builder is used to build instances of ULocale from values configured by the setters. 

enum ULocale.Category

Enum for locale categories. 

Constants

char PRIVATE_USE_EXTENSION

The key for the private use locale extension ('x').

char UNICODE_LOCALE_EXTENSION

The key for Unicode locale extension ('u').

Fields

public static final ULocale CANADA

Useful constant for country/region.

public static final ULocale CANADA_FRENCH

Useful constant for country/region.

public static final ULocale CHINA

Useful constant for country/region.

public static final ULocale CHINESE

Useful constant for language.

public static final ULocale ENGLISH

Useful constant for language.

public static final ULocale FRANCE

Useful constant for country/region.

public static final ULocale FRENCH

Useful constant for language.

public static final ULocale GERMAN

Useful constant for language.

public static final ULocale GERMANY

Useful constant for country/region.

public static final ULocale ITALIAN

Useful constant for language.

public static final ULocale ITALY

Useful constant for country/region.

public static final ULocale JAPAN

Useful constant for country/region.

public static final ULocale JAPANESE

Useful constant for language.

public static final ULocale KOREA

Useful constant for country/region.

public static final ULocale KOREAN

Useful constant for language.

public static final ULocale PRC

Useful constant for country/region.

public static final ULocale ROOT

The root ULocale.

public static final ULocale SIMPLIFIED_CHINESE

Useful constant for language.

public static final ULocale TAIWAN

Useful constant for country/region.

public static final ULocale TRADITIONAL_CHINESE

Useful constant for language.

public static final ULocale UK

Useful constant for country/region.

public static final ULocale US

Useful constant for country/region.

Public constructors

ULocale(String localeID)

[icu] Constructs a ULocale from a RFC 3066 locale ID.

ULocale(String a, String b)

Convenience overload of ULocale(String, String, String) for compatibility with java.util.Locale.

ULocale(String a, String b, String c)

Constructs a ULocale from a localeID constructed from the three 'fields' a, b, and c.

Public methods

static ULocale acceptLanguage(ULocale[] acceptLanguageList, boolean[] fallback)

[icu] Based on an ordered array of acceptable locales, determine an available locale for the user.

static ULocale acceptLanguage(String acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)

[icu] Based on a HTTP formatted list of acceptable locales, determine an available locale for the user.

static ULocale acceptLanguage(ULocale[] acceptLanguageList, ULocale[] availableLocales, boolean[] fallback)

[icu] Based on a list of acceptable locales, determine an available locale for the user.

static ULocale acceptLanguage(String acceptLanguageList, boolean[] fallback)

[icu] Based on a HTTP formatted list of acceptable locales, determine an available locale for the user.

static ULocale addLikelySubtags(ULocale loc)

[icu] 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 the provided ULocale instance is already in the maximal form, or there is no data available available for maximization, it will be returned.

static String canonicalize(String localeID)

[icu] Returns the canonical name for the specified locale ID.

Object clone()

This is for compatibility with Locale-- in actuality, since ULocale is immutable, there is no reason to clone it, so this API returns 'this'.

int compareTo(ULocale other)

Compares two ULocale for ordering.

static ULocale createCanonical(String nonCanonicalID)

[icu] Creates a ULocale from the id by first canonicalizing the id.

boolean equals(Object obj)

Returns true if the other object is another ULocale with the same full name.

static ULocale forLanguageTag(String languageTag)

Returns a locale for the specified IETF BCP 47 language tag string.

static ULocale forLocale(Locale loc)

[icu] Returns a ULocale object for a Locale.

static ULocale[] getAvailableLocales()

[icu] Note: Unlike the Locale API, this returns an array of ULocale, not Locale.

String getBaseName()

[icu] Returns the (normalized) base name for this locale, like getName(), but without keywords.

static String getBaseName(String localeID)

[icu] Returns the (normalized) base name for the specified locale, like getName(String), but without keywords.

String getCharacterOrientation()

[icu] Returns this locale's layout orientation for characters.

static String getCountry(String localeID)

[icu] Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.

String getCountry()

Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.

static ULocale getDefault()

Returns the current default ULocale.

static ULocale getDefault(ULocale.Category category)

Returns the current default ULocale for the specified category.

String getDisplayCountry()

Returns this locale's country localized for display in the default DISPLAY locale.

static String getDisplayCountry(String localeID, String displayLocaleID)

[icu] Returns a locale's country localized for display in the provided locale.

String getDisplayCountry(ULocale displayLocale)

Returns this locale's country localized for display in the provided locale.

static String getDisplayCountry(String localeID, ULocale displayLocale)

[icu] Returns a locale's country localized for display in the provided locale.

static String getDisplayKeyword(String keyword, ULocale displayLocale)

[icu] Returns a keyword localized for display in the specified locale.

static String getDisplayKeyword(String keyword, String displayLocaleID)

[icu] Returns a keyword localized for display in the specified locale.

static String getDisplayKeyword(String keyword)

[icu] Returns a keyword localized for display in the default DISPLAY locale.

static String getDisplayKeywordValue(String localeID, String keyword, String displayLocaleID)

[icu] Returns a keyword value localized for display in the specified locale.

static String getDisplayKeywordValue(String localeID, String keyword, ULocale displayLocale)

[icu] Returns a keyword value localized for display in the specified locale.

String getDisplayKeywordValue(String keyword)

[icu] Returns a keyword value localized for display in the default DISPLAY locale.

String getDisplayKeywordValue(String keyword, ULocale displayLocale)

[icu] Returns a keyword value localized for display in the specified locale.

String getDisplayLanguage(ULocale displayLocale)

Returns this locale's language localized for display in the provided locale.

static String getDisplayLanguage(String localeID, ULocale displayLocale)

[icu] Returns a locale's language localized for display in the provided locale.

static String getDisplayLanguage(String localeID, String displayLocaleID)

[icu] Returns a locale's language localized for display in the provided locale.

String getDisplayLanguage()

Returns this locale's language localized for display in the default DISPLAY locale.

String getDisplayLanguageWithDialect(ULocale displayLocale)

[icu] Returns this locale's language localized for display in the provided locale.

static String getDisplayLanguageWithDialect(String localeID, String displayLocaleID)

[icu] Returns a locale's language localized for display in the provided locale.

static String getDisplayLanguageWithDialect(String localeID, ULocale displayLocale)

[icu] Returns a locale's language localized for display in the provided locale.

String getDisplayLanguageWithDialect()

[icu] Returns this locale's language localized for display in the default DISPLAY locale.

String getDisplayName()

Returns this locale name localized for display in the default DISPLAY locale.

String getDisplayName(ULocale displayLocale)

Returns this locale name localized for display in the provided locale.

static String getDisplayName(String localeID, String displayLocaleID)

[icu] Returns the locale ID localized for display in the provided locale.

static String getDisplayName(String localeID, ULocale displayLocale)

[icu] Returns the locale ID localized for display in the provided locale.

static String getDisplayNameWithDialect(String localeID, String displayLocaleID)

[icu] Returns the locale ID localized for display in the provided locale.

static String getDisplayNameWithDialect(String localeID, ULocale displayLocale)

[icu] Returns the locale ID localized for display in the provided locale.

String getDisplayNameWithDialect(ULocale displayLocale)

[icu] Returns this locale name localized for display in the provided locale.

String getDisplayNameWithDialect()

[icu] Returns this locale name localized for display in the default DISPLAY locale.

static String getDisplayScript(String localeID, String displayLocaleID)

[icu] Returns a locale's script localized for display in the provided locale.

static String getDisplayScript(String localeID, ULocale displayLocale)

[icu] Returns a locale's script localized for display in the provided locale.

String getDisplayScript()

Returns this locale's script localized for display in the default DISPLAY locale.

String getDisplayScript(ULocale displayLocale)

Returns this locale's script localized for display in the provided locale.

static String getDisplayVariant(String localeID, String displayLocaleID)

[icu] Returns a locale's variant localized for display in the provided locale.

String getDisplayVariant()

Returns this locale's variant localized for display in the default DISPLAY locale.

String getDisplayVariant(ULocale displayLocale)

Returns this locale's variant localized for display in the provided locale.

static String getDisplayVariant(String localeID, ULocale displayLocale)

[icu] Returns a locale's variant localized for display in the provided locale.

String getExtension(char key)

Returns the extension (or private use) value associated with the specified key, or null if there is no extension associated with the key.

Set<Character> getExtensionKeys()

Returns the set of extension keys associated with this locale, or the empty set if it has no extensions.

ULocale getFallback()

[icu] Returns the fallback locale for this locale.

static String getFallback(String localeID)

[icu] Returns the fallback locale for the specified locale, which might be the empty string.

String getISO3Country()

Returns a three-letter abbreviation for this locale's country/region.

static String getISO3Country(String localeID)

[icu] Returns a three-letter abbreviation for this locale's country/region.

String getISO3Language()

Returns a three-letter abbreviation for this locale's language.

static String getISO3Language(String localeID)

[icu] Returns a three-letter abbreviation for this locale's language.

static String[] getISOCountries()

Returns a list of all 2-letter country codes defined in ISO 3166.

static String[] getISOLanguages()

Returns a list of all 2-letter language codes defined in ISO 639.

static String getKeywordValue(String localeID, String keywordName)

[icu] Returns the value for a keyword in the specified locale.

String getKeywordValue(String keywordName)

[icu] Returns the value for a keyword in this locale.

static Iterator<String> getKeywords(String localeID)

[icu] Returns an iterator over keywords for the specified locale.

Iterator<String> getKeywords()

[icu] Returns an iterator over keywords for this locale.

static String getLanguage(String localeID)

Returns the language code for the locale ID, which will either be the empty string or a lowercase ISO 639 code.

String getLanguage()

Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code.

String getLineOrientation()

[icu] Returns this locale's layout orientation for lines.

String getName()

[icu] Returns the (normalized) full name for this locale.

static String getName(String localeID)

[icu] Returns the (normalized) full name for the specified locale.

String getScript()

Returns the script code for this locale, which might be the empty string.

static String getScript(String localeID)

[icu] Returns the script code for the specified locale, which might be the empty string.

Set<String> getUnicodeLocaleAttributes()

Returns the set of unicode locale attributes associated with this locale, or the empty set if it has no attributes.

Set<String> getUnicodeLocaleKeys()

Returns the set of Unicode locale keys defined by this locale, or the empty set if this locale has none.

String getUnicodeLocaleType(String key)

Returns the Unicode locale type associated with the specified Unicode locale key for this locale.

String getVariant()

Returns the variant code for this locale, which might be the empty string.

static String getVariant(String localeID)

[icu] Returns the variant code for the specified locale, which might be the empty string.

int hashCode()

Returns the hashCode.

boolean isRightToLeft()

[icu] Returns whether this locale's script is written right-to-left.

static ULocale minimizeSubtags(ULocale loc)

[icu] 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 the provided ULocale instance is already in the minimal form, or there is no data available for minimization, it will be returned.

ULocale setKeywordValue(String keyword, String value)

[icu] Given a keyword and a value, return a new locale with an updated keyword and value.

static String setKeywordValue(String localeID, String keyword, String value)

Given a locale id, a keyword, and a value, return a new locale id with an updated keyword and value.

String toLanguageTag()

Returns a well-formed IETF BCP 47 language tag representing this locale.

static String toLegacyKey(String keyword)

[icu] Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key.

static String toLegacyType(String keyword, String value)

[icu] Converts the specified keyword value (BCP 47 Unicode locale extension type, or legacy type or type alias) to the canonical legacy type.

Locale toLocale()

[icu] Converts this ULocale object to a Locale.

String toString()

Returns a string representation of this object.

static String toUnicodeLocaleKey(String keyword)

[icu] Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent BCP 47 Unicode locale extension key.

static String toUnicodeLocaleType(String keyword, String value)

[icu] Converts the specified keyword value (legacy type, or BCP 47 Unicode locale extension type) to the well-formed BCP 47 Unicode locale extension type for the specified keyword (category).

Inherited methods

Constants

PRIVATE_USE_EXTENSION

added in API level 24
char PRIVATE_USE_EXTENSION

The key for the private use locale extension ('x').

Constant Value: 120 (0x00000078)

UNICODE_LOCALE_EXTENSION

added in API level 24
char UNICODE_LOCALE_EXTENSION

The key for Unicode locale extension ('u').

Constant Value: 117 (0x00000075)

Fields

CANADA

added in API level 24
ULocale CANADA

Useful constant for country/region.

CANADA_FRENCH

added in API level 24
ULocale CANADA_FRENCH

Useful constant for country/region.

CHINA

added in API level 24
ULocale CHINA

Useful constant for country/region.

CHINESE

added in API level 24
ULocale CHINESE

Useful constant for language.

ENGLISH

added in API level 24
ULocale ENGLISH

Useful constant for language.

FRANCE

added in API level 24
ULocale FRANCE

Useful constant for country/region.

FRENCH

added in API level 24
ULocale FRENCH

Useful constant for language.

GERMAN

added in API level 24
ULocale GERMAN

Useful constant for language.

GERMANY

added in API level 24
ULocale GERMANY

Useful constant for country/region.

ITALIAN

added in API level 24
ULocale ITALIAN

Useful constant for language.

ITALY

added in API level 24
ULocale ITALY

Useful constant for country/region.

JAPAN

added in API level 24
ULocale JAPAN

Useful constant for country/region.

JAPANESE

added in API level 24
ULocale JAPANESE

Useful constant for language.

KOREA

added in API level 24
ULocale KOREA

Useful constant for country/region.

KOREAN

added in API level 24
ULocale KOREAN

Useful constant for language.

PRC

added in API level 24
ULocale PRC

Useful constant for country/region.

ROOT

added in API level 24
ULocale ROOT

The root ULocale.

SIMPLIFIED_CHINESE

added in API level 24
ULocale SIMPLIFIED_CHINESE

Useful constant for language.

TAIWAN

added in API level 24
ULocale TAIWAN

Useful constant for country/region.

TRADITIONAL_CHINESE

added in API level 24
ULocale TRADITIONAL_CHINESE

Useful constant for language.

UK

added in API level 24
ULocale UK

Useful constant for country/region.

US

added in API level 24
ULocale US

Useful constant for country/region.

Public constructors

ULocale

added in API level 24
ULocale (String localeID)

[icu] Constructs a ULocale from a RFC 3066 locale ID. The locale ID consists of optional language, script, country, and variant fields in that order, separated by underscores, followed by an optional keyword list. The script, if present, is four characters long-- this distinguishes it from a country code, which is two characters long. Other fields are distinguished by position as indicated by the underscores. The start of the keyword list is indicated by '@', and consists of two or more keyword/value pairs separated by semicolons(';').

This constructor does not canonicalize the localeID. So, for example, "zh__pinyin" remains unchanged instead of converting to "zh@collation=pinyin". By default ICU only recognizes the latter as specifying pinyin collation. Use createCanonical(String) or canonicalize(String) if you need to canonicalize the localeID.

Parameters
localeID String: string representation of the locale, e.g: "en_US", "sy_Cyrl_YU", "zh__pinyin", "es_ES@currency=EUR;collation=traditional"

ULocale

added in API level 24
ULocale (String a, 
                String b)

Convenience overload of ULocale(String, String, String) for compatibility with java.util.Locale.

Parameters
a String

b String

ULocale

added in API level 24
ULocale (String a, 
                String b, 
                String c)

Constructs a ULocale from a localeID constructed from the three 'fields' a, b, and c. These fields are concatenated using underscores to form a localeID of the form a_b_c, which is then handled like the localeID passed to ULocale(String localeID).

Java locale strings consisting of language, country, and variant will be handled by this form, since the country code (being shorter than four letters long) will not be interpreted as a script code. If a script code is present, the final argument ('c') will be interpreted as the country code. It is recommended that this constructor only be used to ease porting, and that clients instead use the single-argument constructor when constructing a ULocale from a localeID.

Parameters
a String: first component of the locale id

b String: second component of the locale id

c String: third component of the locale id

See also:

Public methods

acceptLanguage

added in API level 24
ULocale acceptLanguage (ULocale[] acceptLanguageList, 
                boolean[] fallback)

[icu] Based on an ordered array of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case. This function will choose a locale from the ULocale.getAvailableLocales() list as available.

Parameters
acceptLanguageList ULocale: ordered array of acceptable locales (preferred are listed first)

fallback boolean: if non-null, a 1-element array containing a boolean to be set with the fallback status

Returns
ULocale one of the locales from the ULocale.getAvailableLocales() list, or null if none match

acceptLanguage

added in API level 24
ULocale acceptLanguage (String acceptLanguageList, 
                ULocale[] availableLocales, 
                boolean[] fallback)

[icu] Based on a HTTP formatted list of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case.

Parameters
acceptLanguageList String: list in HTTP "Accept-Language:" format of acceptable locales

availableLocales ULocale: list of available locales. One of these will be returned.

fallback boolean: if non-null, a 1-element array containing a boolean to be set with the fallback status

Returns
ULocale one of the locales from the availableLocales list, or null if none match

acceptLanguage

added in API level 24
ULocale acceptLanguage (ULocale[] acceptLanguageList, 
                ULocale[] availableLocales, 
                boolean[] fallback)

[icu] Based on a list of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case.

Parameters
acceptLanguageList ULocale: list of acceptable locales

availableLocales ULocale: list of available locales. One of these will be returned.

fallback boolean: if non-null, a 1-element array containing a boolean to be set with the fallback status

Returns
ULocale one of the locales from the availableLocales list, or null if none match

acceptLanguage

added in API level 24
ULocale acceptLanguage (String acceptLanguageList, 
                boolean[] fallback)

[icu] Based on a HTTP formatted list of acceptable locales, determine an available locale for the user. NullPointerException is thrown if acceptLanguageList or availableLocales is null. If fallback is non-null, it will contain true if a fallback locale (one not in the acceptLanguageList) was returned. The value on entry is ignored. ULocale will be one of the locales in availableLocales, or the ROOT ULocale if if a ROOT locale was used as a fallback (because nothing else in availableLocales matched). No ULocale array element should be null; behavior is undefined if this is the case. This function will choose a locale from the ULocale.getAvailableLocales() list as available.

Parameters
acceptLanguageList String: list in HTTP "Accept-Language:" format of acceptable locales

fallback boolean: if non-null, a 1-element array containing a boolean to be set with the fallback status

Returns
ULocale one of the locales from the ULocale.getAvailableLocales() list, or null if none match

addLikelySubtags

added in API level 24
ULocale addLikelySubtags (ULocale loc)

[icu] 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 the provided ULocale instance is already in the maximal form, or there is no data available available for maximization, it will be returned. For example, "und-Zzzz" cannot be maximized, since there is no reasonable maximization. Otherwise, a new ULocale instance with the maximal form is returned. 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.)

Parameters
loc ULocale: The ULocale to maximize

Returns
ULocale The maximized ULocale instance.

canonicalize

added in API level 24
String canonicalize (String localeID)

[icu] Returns the canonical name for the specified locale ID. This is used to convert POSIX and other grandfathered IDs to standard ICU form.

Parameters
localeID String: the locale id

Returns
String the canonicalized id

clone

added in API level 24
Object clone ()

This is for compatibility with Locale-- in actuality, since ULocale is immutable, there is no reason to clone it, so this API returns 'this'.

Returns
Object a clone of this instance.

compareTo

added in API level 24
int compareTo (ULocale other)

Compares two ULocale for ordering.

Note: The order might change in future.

Parameters
other ULocale: the ULocale to be compared.

Returns
int a negative integer, zero, or a positive integer as this ULocale is less than, equal to, or greater than the specified ULocale.

Throws
NullPointerException if other is null.

createCanonical

added in API level 24
ULocale createCanonical (String nonCanonicalID)

[icu] Creates a ULocale from the id by first canonicalizing the id.

Parameters
nonCanonicalID String: the locale id to canonicalize

Returns
ULocale the locale created from the canonical version of the ID.

equals

added in API level 24
boolean equals (Object obj)

Returns true if the other object is another ULocale with the same full name. Note that since names are not canonicalized, two ULocales that function identically might not compare equal.

Parameters
obj Object: the reference object with which to compare.

Returns
boolean true if this Locale is equal to the specified object.

forLanguageTag

added in API level 24
ULocale forLanguageTag (String languageTag)

Returns a locale for the specified IETF BCP 47 language tag string.

If the specified language tag contains any ill-formed subtags, the first such subtag and all following subtags are ignored. Compare to setLanguageTag(String) which throws an exception in this case.

The following conversions are performed:

  • The language code "und" is mapped to language "".
  • The portion of a private use subtag prefixed by "lvariant", if any, is removed and appended to the variant field in the result locale (without case normalization). If it is then empty, the private use subtag is discarded:
         ULocale loc;
         loc = ULocale.forLanguageTag("en-US-x-lvariant-icu4j);
         loc.getVariant(); // returns "ICU4J"
         loc.getExtension('x'); // returns null
    
         loc = Locale.forLanguageTag("de-icu4j-x-URP-lvariant-Abc-Def");
         loc.getVariant(); // returns "ICU4J_ABC_DEF"
         loc.getExtension('x'); // returns "urp"
     
  • When the languageTag argument contains an extlang subtag, the first such subtag is used as the language, and the primary language subtag and other extlang subtags are ignored:
         ULocale.forLanguageTag("ar-aao").getLanguage(); // returns "aao"
         ULocale.forLanguageTag("en-abc-def-us").toString(); // returns "abc_US"
     
  • Case is normalized. Language is normalized to lower case, script to title case, country to upper case, variant to upper case, and extensions to lower case.

This implements the 'Language-Tag' production of BCP47, and so supports grandfathered (regular and irregular) as well as private use language tags. Stand alone private use tags are represented as empty language and extension 'x-whatever', and grandfathered tags are converted to their canonical replacements where they exist.

Grandfathered tags with canonical replacements are as follows:

grandfathered tag modern replacement
art-lojban jbo
i-ami ami
i-bnn bnn
i-hak hak
i-klingon tlh
i-lux lb
i-navajo nv
i-pwn pwn
i-tao tao
i-tay tay
i-tsu tsu
no-bok nb
no-nyn nn
sgn-BE-FR sfb
sgn-BE-NL vgt
sgn-CH-DE sgg
zh-guoyu cmn
zh-hakka hak
zh-min-nan nan
zh-xiang hsn

Grandfathered tags with no modern replacement will be converted as follows:

grandfathered tag converts to
cel-gaulish xtg-x-cel-gaulish
en-GB-oed en-GB-x-oed
i-default en-x-i-default
i-enochian und-x-i-enochian
i-mingo see-x-i-mingo
zh-min nan-x-zh-min

For a list of all grandfathered tags, see the IANA Language Subtag Registry (search for "Type: grandfathered").

Note: there is no guarantee that toLanguageTag and forLanguageTag will round-trip.

Parameters
languageTag String: the language tag

Returns
ULocale The locale that best represents the language tag.

Throws
NullPointerException if languageTag is null

forLocale

added in API level 24
ULocale forLocale (Locale loc)

[icu] Returns a ULocale object for a Locale. The ULocale is canonicalized.

Parameters
loc Locale: a Locale

Returns
ULocale

getAvailableLocales

added in API level 24
ULocale[] getAvailableLocales ()

[icu] Note: Unlike the Locale API, this returns an array of ULocale, not Locale. Returns a list of all installed locales.

Returns
ULocale[]

getBaseName

added in API level 24
String getBaseName ()

[icu] Returns the (normalized) base name for this locale, like getName(), but without keywords.

Returns
String the base name as a String.

getBaseName

added in API level 24
String getBaseName (String localeID)

[icu] Returns the (normalized) base name for the specified locale, like getName(String), but without keywords.

Parameters
localeID String: the locale ID as a string

Returns
String the base name as a String.

getCharacterOrientation

added in API level 24
String getCharacterOrientation ()

[icu] Returns this locale's layout orientation for characters. The possible values are "left-to-right", "right-to-left", "top-to-bottom" or "bottom-to-top".

Returns
String The locale's layout orientation for characters.

getCountry

added in API level 24
String getCountry (String localeID)

[icu] Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.

Parameters
localeID String: The locale identification string.

Returns
String

getCountry

added in API level 24
String getCountry ()

Returns the country/region code for this locale, which will either be the empty string or an uppercase ISO 3166 2-letter code.

Returns
String

getDefault

added in API level 24
ULocale getDefault ()

Returns the current default ULocale.

The default ULocale is synchronized to the default Java Locale. This method checks the current default Java Locale and returns an equivalent ULocale.

Returns
ULocale the default ULocale.

getDefault

added in API level 24
ULocale getDefault (ULocale.Category category)

Returns the current default ULocale for the specified category.

Parameters
category ULocale.Category: the category

Returns
ULocale the default ULocale for the specified category.

getDisplayCountry

added in API level 24
String getDisplayCountry ()

Returns this locale's country localized for display in the default DISPLAY locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, use LocaleDisplayNames instead.

Returns
String the localized country name.

See also:

getDisplayCountry

added in API level 24
String getDisplayCountry (String localeID, 
                String displayLocaleID)

[icu] Returns a locale's country localized for display in the provided locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, use LocaleDisplayNames instead. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose country will be displayed

displayLocaleID String: the id of the locale in which to display the name.

Returns
String the localized country name.

getDisplayCountry

added in API level 24
String getDisplayCountry (ULocale displayLocale)

Returns this locale's country localized for display in the provided locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, use LocaleDisplayNames instead.

Parameters
displayLocale ULocale: the locale in which to display the name.

Returns
String the localized country name.

getDisplayCountry

added in API level 24
String getDisplayCountry (String localeID, 
                ULocale displayLocale)

[icu] Returns a locale's country localized for display in the provided locale. Warning: this is for the region part of a valid locale ID; it cannot just be the region code (like "FR"). To get the display name for a region alone, or for other options, use LocaleDisplayNames instead. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose country will be displayed.

displayLocale ULocale: the locale in which to display the name.

Returns
String the localized country name.

getDisplayKeyword

added in API level 24
String getDisplayKeyword (String keyword, 
                ULocale displayLocale)

[icu] Returns a keyword localized for display in the specified locale.

Parameters
keyword String: the keyword to be displayed.

displayLocale ULocale: the locale in which to display the keyword.

Returns
String the localized keyword name.

getDisplayKeyword

added in API level 24
String getDisplayKeyword (String keyword, 
                String displayLocaleID)

[icu] Returns a keyword localized for display in the specified locale.

Parameters
keyword String: the keyword to be displayed.

displayLocaleID String: the id of the locale in which to display the keyword.

Returns
String the localized keyword name.

getDisplayKeyword

added in API level 24
String getDisplayKeyword (String keyword)

[icu] Returns a keyword localized for display in the default DISPLAY locale.

Parameters
keyword String: the keyword to be displayed.

Returns
String the localized keyword name.

getDisplayKeywordValue

added in API level 24
String getDisplayKeywordValue (String localeID, 
                String keyword, 
                String displayLocaleID)

[icu] Returns a keyword value localized for display in the specified locale. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose keyword value is to be displayed.

keyword String: the keyword whose value is to be displayed.

displayLocaleID String: the id of the locale in which to display the value.

Returns
String the localized value name.

getDisplayKeywordValue

added in API level 24
String getDisplayKeywordValue (String localeID, 
                String keyword, 
                ULocale displayLocale)

[icu] Returns a keyword value localized for display in the specified locale. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose keyword value is to be displayed.

keyword String: the keyword whose value is to be displayed.

displayLocale ULocale: the id of the locale in which to display the value.

Returns
String the localized value name.

getDisplayKeywordValue

added in API level 24
String getDisplayKeywordValue (String keyword)

[icu] Returns a keyword value localized for display in the default DISPLAY locale.

Parameters
keyword String: the keyword whose value is to be displayed.

Returns
String the localized value name.

See also:

getDisplayKeywordValue

added in API level 24
String getDisplayKeywordValue (String keyword, 
                ULocale displayLocale)

[icu] Returns a keyword value localized for display in the specified locale.

Parameters
keyword String: the keyword whose value is to be displayed.

displayLocale ULocale: the locale in which to display the value.

Returns
String the localized value name.

getDisplayLanguage

added in API level 24
String getDisplayLanguage (ULocale displayLocale)

Returns this locale's language localized for display in the provided locale.

Parameters
displayLocale ULocale: the locale in which to display the name.

Returns
String the localized language name.

getDisplayLanguage

added in API level 24
String getDisplayLanguage (String localeID, 
                ULocale displayLocale)

[icu] Returns a locale's language localized for display in the provided locale. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose language will be displayed.

displayLocale ULocale: the locale in which to display the name.

Returns
String the localized language name.

getDisplayLanguage

added in API level 24
String getDisplayLanguage (String localeID, 
                String displayLocaleID)

[icu] Returns a locale's language localized for display in the provided locale. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose language will be displayed

displayLocaleID String: the id of the locale in which to display the name.

Returns
String the localized language name.

getDisplayLanguage

added in API level 24
String getDisplayLanguage ()

Returns this locale's language localized for display in the default DISPLAY locale.

Returns
String the localized language name.

See also:

getDisplayLanguageWithDialect

added in API level 24
String getDisplayLanguageWithDialect (ULocale displayLocale)

[icu] Returns this locale's language localized for display in the provided locale. If a dialect name is present in the data, then it is returned.

Parameters
displayLocale ULocale: the locale in which to display the name.

Returns
String the localized language name.

getDisplayLanguageWithDialect

added in API level 24
String getDisplayLanguageWithDialect (String localeID, 
                String displayLocaleID)

[icu] Returns a locale's language localized for display in the provided locale. If a dialect name is present in the data, then it is returned. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose language will be displayed

displayLocaleID String: the id of the locale in which to display the name.

Returns
String the localized language name.

getDisplayLanguageWithDialect

added in API level 24
String getDisplayLanguageWithDialect (String localeID, 
                ULocale displayLocale)

[icu] Returns a locale's language localized for display in the provided locale. If a dialect name is present in the data, then it is returned. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose language will be displayed.

displayLocale ULocale: the locale in which to display the name.

Returns
String the localized language name.

getDisplayLanguageWithDialect

added in API level 24
String getDisplayLanguageWithDialect ()

[icu] Returns this locale's language localized for display in the default DISPLAY locale. If a dialect name is present in the data, then it is returned.

Returns
String the localized language name.

See also:

getDisplayName

added in API level 24
String getDisplayName ()

Returns this locale name localized for display in the default DISPLAY locale.

Returns
String the localized locale name.

See also:

getDisplayName

added in API level 24
String getDisplayName (ULocale displayLocale)

Returns this locale name localized for display in the provided locale.

Parameters
displayLocale ULocale: the locale in which to display the locale name.

Returns
String the localized locale name.

getDisplayName

added in API level 24
String getDisplayName (String localeID, 
                String displayLocaleID)

[icu] Returns the locale ID localized for display in the provided locale. This is a cover for the ICU4C API.

Parameters
localeID String: the locale whose name is to be displayed.

displayLocaleID String: the id of the locale in which to display the locale name.

Returns
String the localized locale name.

getDisplayName

added in API level 24
String getDisplayName (String localeID, 
                ULocale displayLocale)

[icu] Returns the locale ID localized for display in the provided locale. This is a cover for the ICU4C API.

Parameters
localeID String: the locale whose name is to be displayed.

displayLocale ULocale: the locale in which to display the locale name.

Returns
String the localized locale name.

getDisplayNameWithDialect

added in API level 24
String getDisplayNameWithDialect (String localeID, 
                String displayLocaleID)

[icu] Returns the locale ID localized for display in the provided locale. If a dialect name is present in the locale data, then it is returned. This is a cover for the ICU4C API.

Parameters
localeID String: the locale whose name is to be displayed.

displayLocaleID String: the id of the locale in which to display the locale name.

Returns
String the localized locale name.

getDisplayNameWithDialect

added in API level 24
String getDisplayNameWithDialect (String localeID, 
                ULocale displayLocale)

[icu] Returns the locale ID localized for display in the provided locale. If a dialect name is present in the locale data, then it is returned. This is a cover for the ICU4C API.

Parameters
localeID String: the locale whose name is to be displayed.

displayLocale ULocale: the locale in which to display the locale name.

Returns
String the localized locale name.

getDisplayNameWithDialect

added in API level 24
String getDisplayNameWithDialect (ULocale displayLocale)

[icu] Returns this locale name localized for display in the provided locale. If a dialect name is present in the locale data, then it is returned.

Parameters
displayLocale ULocale: the locale in which to display the locale name.

Returns
String the localized locale name.

getDisplayNameWithDialect

added in API level 24
String getDisplayNameWithDialect ()

[icu] Returns this locale name localized for display in the default DISPLAY locale. If a dialect name is present in the locale data, then it is returned.

Returns
String the localized locale name.

See also:

getDisplayScript

added in API level 24
String getDisplayScript (String localeID, 
                String displayLocaleID)

[icu] Returns a locale's script localized for display in the provided locale. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose script will be displayed

displayLocaleID String: the id of the locale in which to display the name.

Returns
String the localized script name.

getDisplayScript

added in API level 24
String getDisplayScript (String localeID, 
                ULocale displayLocale)

[icu] Returns a locale's script localized for display in the provided locale.

Parameters
localeID String: the id of the locale whose script will be displayed.

displayLocale ULocale: the locale in which to display the name.

Returns
String the localized script name.

getDisplayScript

added in API level 24
String getDisplayScript ()

Returns this locale's script localized for display in the default DISPLAY locale.

Returns
String the localized script name.

See also:

getDisplayScript

added in API level 24
String getDisplayScript (ULocale displayLocale)

Returns this locale's script localized for display in the provided locale.

Parameters
displayLocale ULocale: the locale in which to display the name.

Returns
String the localized script name.

getDisplayVariant

added in API level 24
String getDisplayVariant (String localeID, 
                String displayLocaleID)

[icu] Returns a locale's variant localized for display in the provided locale. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose variant will be displayed

displayLocaleID String: the id of the locale in which to display the name.

Returns
String the localized variant name.

getDisplayVariant

added in API level 24
String getDisplayVariant ()

Returns this locale's variant localized for display in the default DISPLAY locale.

Returns
String the localized variant name.

See also:

getDisplayVariant

added in API level 24
String getDisplayVariant (ULocale displayLocale)

Returns this locale's variant localized for display in the provided locale.

Parameters
displayLocale ULocale: the locale in which to display the name.

Returns
String the localized variant name.

getDisplayVariant

added in API level 24
String getDisplayVariant (String localeID, 
                ULocale displayLocale)

[icu] Returns a locale's variant localized for display in the provided locale. This is a cover for the ICU4C API.

Parameters
localeID String: the id of the locale whose variant will be displayed.

displayLocale ULocale: the locale in which to display the name.

Returns
String the localized variant name.

getExtension

added in API level 24
String getExtension (char key)

Returns the extension (or private use) value associated with the specified key, or null if there is no extension associated with the key. To be well-formed, the key must be one of [0-9A-Za-z]. Keys are case-insensitive, so for example 'z' and 'Z' represent the same extension.

Parameters
key char: the extension key

Returns
String The extension, or null if this locale defines no extension for the specified key.

Throws
IllegalArgumentException if key is not well-formed

getExtensionKeys

added in API level 24
Set<Character> getExtensionKeys ()

Returns the set of extension keys associated with this locale, or the empty set if it has no extensions. The returned set is unmodifiable. The keys will all be lower-case.

Returns
Set<Character> the set of extension keys, or the empty set if this locale has no extensions

getFallback

added in API level 24
ULocale getFallback ()

[icu] Returns the fallback locale for this locale. If this locale is root, returns null.

Returns
ULocale

getFallback

added in API level 24
String getFallback (String localeID)

[icu] Returns the fallback locale for the specified locale, which might be the empty string.

Parameters
localeID String

Returns
String

getISO3Country

added in API level 24
String getISO3Country ()

Returns a three-letter abbreviation for this locale's country/region. If the locale doesn't specify a country, returns the empty string. Otherwise, returns an uppercase ISO 3166 3-letter country code.

Returns
String

Throws
MissingResourceException Throws MissingResourceException if the three-letter country abbreviation is not available for this locale.

getISO3Country

added in API level 24
String getISO3Country (String localeID)

[icu] Returns a three-letter abbreviation for this locale's country/region. If the locale doesn't specify a country, returns the empty string. Otherwise, returns an uppercase ISO 3166 3-letter country code.

Parameters
localeID String

Returns
String

Throws
MissingResourceException Throws MissingResourceException if the three-letter country abbreviation is not available for this locale.

getISO3Language

added in API level 24
String getISO3Language ()

Returns a three-letter abbreviation for this locale's language. If the locale doesn't specify a language, returns the empty string. Otherwise, returns a lowercase ISO 639-2/T language code. The ISO 639-2 language codes can be found on-line at ftp://dkuug.dk/i18n/iso-639-2.txt

Returns
String

Throws
MissingResourceException Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.

getISO3Language

added in API level 24
String getISO3Language (String localeID)

[icu] Returns a three-letter abbreviation for this locale's language. If the locale doesn't specify a language, returns the empty string. Otherwise, returns a lowercase ISO 639-2/T language code. The ISO 639-2 language codes can be found on-line at ftp://dkuug.dk/i18n/iso-639-2.txt

Parameters
localeID String

Returns
String

Throws
MissingResourceException Throws MissingResourceException if the three-letter language abbreviation is not available for this locale.

getISOCountries

added in API level 24
String[] getISOCountries ()

Returns a list of all 2-letter country codes defined in ISO 3166. Can be used to create Locales.

Returns
String[]

getISOLanguages

added in API level 24
String[] getISOLanguages ()

Returns a list of all 2-letter language codes defined in ISO 639. Can be used to create Locales. [NOTE: ISO 639 is not a stable standard-- some languages' codes have changed. The list this function returns includes both the new and the old codes for the languages whose codes have changed.]

Returns
String[]

getKeywordValue

added in API level 24
String getKeywordValue (String localeID, 
                String keywordName)

[icu] Returns the value for a keyword in the specified locale. If the keyword is not defined, returns null. The locale name does not need to be normalized.

Parameters
localeID String

keywordName String: name of the keyword whose value is desired. Case insensitive.

Returns
String String the value of the keyword as a string

getKeywordValue

added in API level 24
String getKeywordValue (String keywordName)

[icu] Returns the value for a keyword in this locale. If the keyword is not defined, returns null.

Parameters
keywordName String: name of the keyword whose value is desired. Case insensitive.

Returns
String the value of the keyword, or null.

getKeywords

added in API level 24
Iterator<String> getKeywords (String localeID)

[icu] Returns an iterator over keywords for the specified locale. If there are no keywords, returns null.

Parameters
localeID String

Returns
Iterator<String> an iterator over the keywords in the specified locale, or null if there are no keywords.

getKeywords

added in API level 24
Iterator<String> getKeywords ()

[icu] Returns an iterator over keywords for this locale. If there are no keywords, returns null.

Returns
Iterator<String> iterator over keywords, or null if there are no keywords.

getLanguage

added in API level 24
String getLanguage (String localeID)

Returns the language code for the locale ID, which will either be the empty string or a lowercase ISO 639 code.

Parameters
localeID String

Returns
String

getLanguage

added in API level 24
String getLanguage ()

Returns the language code for this locale, which will either be the empty string or a lowercase ISO 639 code.

Returns
String

getLineOrientation

added in API level 24
String getLineOrientation ()

[icu] Returns this locale's layout orientation for lines. The possible values are "left-to-right", "right-to-left", "top-to-bottom" or "bottom-to-top".

Returns
String The locale's layout orientation for lines.

getName

added in API level 24
String getName ()

[icu] Returns the (normalized) full name for this locale.

Returns
String String the full name of the localeID

getName

added in API level 24
String getName (String localeID)

[icu] Returns the (normalized) full name for the specified locale.

Parameters
localeID String: the localeID as a string

Returns
String String the full name of the localeID

getScript

added in API level 24
String getScript ()

Returns the script code for this locale, which might be the empty string.

Returns
String

getScript

added in API level 24
String getScript (String localeID)

[icu] Returns the script code for the specified locale, which might be the empty string.

Parameters
localeID String

Returns
String

getUnicodeLocaleAttributes

added in API level 24
Set<String> getUnicodeLocaleAttributes ()

Returns the set of unicode locale attributes associated with this locale, or the empty set if it has no attributes. The returned set is unmodifiable.

Returns
Set<String> The set of attributes.

getUnicodeLocaleKeys

added in API level 24
Set<String> getUnicodeLocaleKeys ()

Returns the set of Unicode locale keys defined by this locale, or the empty set if this locale has none. The returned set is immutable. Keys are all lower case.

Returns
Set<String> The set of Unicode locale keys, or the empty set if this locale has no Unicode locale keywords.

getUnicodeLocaleType

added in API level 24
String getUnicodeLocaleType (String key)

Returns the Unicode locale type associated with the specified Unicode locale key for this locale. Returns the empty string for keys that are defined with no type. Returns null if the key is not defined. Keys are case-insensitive. The key must be two alphanumeric characters ([0-9a-zA-Z]), or an IllegalArgumentException is thrown.

Parameters
key String: the Unicode locale key

Returns
String The Unicode locale type associated with the key, or null if the locale does not define the key.

Throws
IllegalArgumentException if the key is not well-formed
NullPointerException if key is null

getVariant

added in API level 24
String getVariant ()

Returns the variant code for this locale, which might be the empty string.

Returns
String

getVariant

added in API level 24
String getVariant (String localeID)

[icu] Returns the variant code for the specified locale, which might be the empty string.

Parameters
localeID String

Returns
String

hashCode

added in API level 24
int hashCode ()

Returns the hashCode.

Returns
int a hash code value for this object.

isRightToLeft

added in API level 24
boolean isRightToLeft ()

[icu] Returns whether this locale's script is written right-to-left. If there is no script subtag, then the likely script is used, see addLikelySubtags(ULocale). If no likely script is known, then false is returned.

A script is right-to-left according to the CLDR script metadata which corresponds to whether the script's letters have Bidi_Class=R or AL.

Returns true for "ar" and "en-Hebr", false for "zh" and "fa-Cyrl".

Returns
boolean true if the locale's script is written right-to-left

minimizeSubtags

added in API level 24
ULocale minimizeSubtags (ULocale loc)

[icu] 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 the provided ULocale instance is already in the minimal form, or there is no data available for minimization, it will be returned. Since the minimization algorithm relies on proper maximization, see the comments for addLikelySubtags 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".) 

Parameters
loc ULocale: The ULocale to minimize

Returns
ULocale The minimized ULocale instance.

setKeywordValue

added in API level 24
ULocale setKeywordValue (String keyword, 
                String value)

[icu] Given a keyword and a value, return a new locale with an updated keyword and value. If the keyword is null, this removes all keywords from the locale id. Otherwise, if the value is null, this removes the value for this keyword from the locale id. Otherwise, this adds/replaces the value for this keyword in the locale id. The keyword and value must not be empty.

Related: getBaseName() returns the locale ID string with all keywords removed.

Parameters
keyword String: the keyword to add/remove, or null to remove all keywords.

value String: the value to add/set, or null to remove this particular keyword.

Returns
ULocale the updated locale

setKeywordValue

added in API level 24
String setKeywordValue (String localeID, 
                String keyword, 
                String value)

Given a locale id, a keyword, and a value, return a new locale id with an updated keyword and value. If the keyword is null, this removes all keywords from the locale id. Otherwise, if the value is null, this removes the value for this keyword from the locale id. Otherwise, this adds/replaces the value for this keyword in the locale id. The keyword and value must not be empty.

Related: getBaseName(String) returns the locale ID string with all keywords removed.

Parameters
localeID String: the locale id to modify

keyword String: the keyword to add/remove, or null to remove all keywords.

value String: the value to add/set, or null to remove this particular keyword.

Returns
String the updated locale id

toLanguageTag

added in API level 24
String toLanguageTag ()

Returns a well-formed IETF BCP 47 language tag representing this locale.

If this ULocale has a language, script, country, or variant that does not satisfy the IETF BCP 47 language tag syntax requirements, this method handles these fields as described below:

Language: If language is empty, or not well-formed (for example "a" or "e2"), it will be emitted as "und" (Undetermined).

Script: If script is not well-formed (for example "12" or "Latin"), it will be omitted.

Country: If country is not well-formed (for example "12" or "USA"), it will be omitted.

Variant: If variant is well-formed, each sub-segment (delimited by '-' or '_') is emitted as a subtag. Otherwise:

  • if all sub-segments match [0-9a-zA-Z]{1,8} (for example "WIN" or "Oracle_JDK_Standard_Edition"), the first ill-formed sub-segment and all following will be appended to the private use subtag. The first appended subtag will be "lvariant", followed by the sub-segments in order, separated by hyphen. For example, "x-lvariant-WIN", "Oracle-x-lvariant-JDK-Standard-Edition".
  • if any sub-segment does not match [0-9a-zA-Z]{1,8}, the variant will be truncated and the problematic sub-segment and all following sub-segments will be omitted. If the remainder is non-empty, it will be emitted as a private use subtag as above (even if the remainder turns out to be well-formed). For example, "Solaris_isjustthecoolestthing" is emitted as "x-lvariant-Solaris", not as "solaris".

Note: Although the language tag created by this method is well-formed (satisfies the syntax requirements defined by the IETF BCP 47 specification), it is not necessarily a valid BCP 47 language tag. For example,

   new Locale("xx", "YY").toLanguageTag();
will return "xx-YY", but the language subtag "xx" and the region subtag "YY" are invalid because they are not registered in the IANA Language Subtag Registry.

Returns
String a BCP47 language tag representing the locale

toLegacyKey

added in API level 24
String toLegacyKey (String keyword)

[icu] Converts the specified keyword (BCP 47 Unicode locale extension key, or legacy key) to the legacy key. For example, legacy key "collation" is returned for the input BCP 47 Unicode locale extension key "co".

Parameters
keyword String: the input locale keyword (either BCP 47 Unicode locale extension key or legacy key).

Returns
String the well-formed legacy key, or null if the specified keyword cannot be mapped to a well-formed legacy key.

toLegacyType

added in API level 24
String toLegacyType (String keyword, 
                String value)

[icu] Converts the specified keyword value (BCP 47 Unicode locale extension type, or legacy type or type alias) to the canonical legacy type. For example, the legacy type "phonebook" is returned for the input BCP 47 Unicode locale extension type "phonebk" with the keyword "collation" (or "co").

When the specified keyword is not recognized, but the specified value satisfies the syntax of legacy key, or when the specified keyword allows 'variable' type and the specified value satisfies the syntax, the lower-case version of the input value will be returned. For example, toLegacyType("Foo", "Bar") returns "bar", toLegacyType("vt", "00A4") returns "00a4".

Parameters
keyword String: the locale keyword (either legacy keyword such as "collation" or BCP 47 Unicode locale extension key such as "co").

value String: the locale keyword value (either BCP 47 Unicode locale extension type such as "phonebk" or legacy keyword value such as "phonebook").

Returns
String the well-formed legacy type, or null if the specified keyword value cannot be mapped to a well-formed legacy type.

toLocale

added in API level 24
Locale toLocale ()

[icu] Converts this ULocale object to a Locale.

Returns
Locale a Locale that either exactly represents this object or is the closest approximation.

toString

added in API level 24
String toString ()

Returns a string representation of this object.

Returns
String a string representation of the object.

toUnicodeLocaleKey

added in API level 24
String toUnicodeLocaleKey (String keyword)

[icu] Converts the specified keyword (legacy key, or BCP 47 Unicode locale extension key) to the equivalent BCP 47 Unicode locale extension key. For example, BCP 47 Unicode locale extension key "co" is returned for the input keyword "collation".

When the specified keyword is unknown, but satisfies the BCP syntax, then the lower-case version of the input keyword will be returned. For example, toUnicodeLocaleKey("ZZ") returns "zz".

Parameters
keyword String: the input locale keyword (either legacy key such as "collation" or BCP 47 Unicode locale extension key such as "co").

Returns
String the well-formed BCP 47 Unicode locale extension key, or null if the specified locale keyword cannot be mapped to a well-formed BCP 47 Unicode locale extension key.

toUnicodeLocaleType

added in API level 24
String toUnicodeLocaleType (String keyword, 
                String value)

[icu] Converts the specified keyword value (legacy type, or BCP 47 Unicode locale extension type) to the well-formed BCP 47 Unicode locale extension type for the specified keyword (category). For example, BCP 47 Unicode locale extension type "phonebk" is returned for the input keyword value "phonebook", with the keyword "collation" (or "co").

When the specified keyword is not recognized, but the specified value satisfies the syntax of the BCP 47 Unicode locale extension type, or when the specified keyword allows 'variable' type and the specified value satisfies the syntax, the lower-case version of the input value will be returned. For example, toUnicodeLocaleType("Foo", "Bar") returns "bar", toUnicodeLocaleType("variableTop", "00A4") returns "00a4".

Parameters
keyword String: the locale keyword (either legacy key such as "collation" or BCP 47 Unicode locale extension key such as "co").

value String: the locale keyword value (either legacy type such as "phonebook" or BCP 47 Unicode locale extension type such as "phonebk").

Returns
String the well-formed BCP47 Unicode locale extension type, or null if the locale keyword value cannot be mapped to a well-formed BCP 47 Unicode locale extension type.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (April 2018 — Developer Survey)