Android Guides | Samples

Java.Util.Locale Class

Locale represents a language/country/variant combination.

See Also: Locale

Syntax

[Android.Runtime.Register("java/util/Locale", DoNotGenerateAcw=true)]
public sealed class Locale : Object, ISerializable, ICloneable, IDisposable

Remarks

Locale represents a language/country/variant combination. Locales are used to alter the presentation of information such as numbers or dates to suit the conventions in the region they describe.

The language codes are two-letter lowercase ISO language codes (such as "en") as defined by . The country codes are two-letter uppercase ISO country codes (such as "US") as defined by . The variant codes are unspecified.

Note that Java uses several deprecated two-letter codes. The Hebrew ("he") language code is rewritten as "iw", Indonesian ("id") as "in", and Yiddish ("yi") as "ji". This rewriting happens even if you construct your own Locale object, not just for instances returned by the various lookup methods.

Available locales

This class' constructors do no error checking. You can create a Locale for languages and countries that don't exist, and you can create instances for combinations that don't exist (such as "de_US" for "German as spoken in the US").

Note that locale data is not necessarily available for any of the locales pre-defined as constants in this class except for en_US, which is the only locale Java guarantees is always available.

It is also a mistake to assume that all devices have the same locales available. A device sold in the US will almost certainly support en_US and es_US, but not necessarily any locales with the same language but different countries (such as en_GB or es_ES), nor any locales for other languages (such as de_DE). The opposite may well be true for a device sold in Europe.

You can use Locale.Default to get an appropriate locale for the user of the device you're running on, or Locale.GetAvailableLocales to get a list of all the locales available on the device you're running on.

Locale data

Note that locale data comes solely from ICU. User-supplied locale service providers (using the java.text.spi or java.util.spi mechanisms) are not supported.

Here are the versions of ICU (and the corresponding CLDR and Unicode versions) used in various Android releases:

Android 1.5 (Cupcake)/Android 1.6 (Donut)/Android 2.0 (Eclair)ICU 3.8
Android 2.2 (Froyo)ICU 4.2
Android 2.3 (Gingerbread)/Android 3.0 (Honeycomb)ICU 4.4
Android 4.0 (Ice Cream Sandwich)
Android 4.1 (Jelly Bean)
Android 4.3 (Jelly Bean MR2)
Android 4.4 (KitKat)
Android 5.0 (Lollipop)
Android 6.0 (Marshmallow)

Be wary of the default locale

Note that there are many convenience methods that automatically use the default locale, but using them may lead to subtle bugs.

The default locale is appropriate for tasks that involve presenting data to the user. In this case, you want to use the user's date/time formats, number formats, rules for conversion to lowercase, and so on. In this case, it's safe to use the convenience methods.

The default locale is not appropriate for machine-readable output. The best choice there is usually Locale.US – this locale is guaranteed to be available on all devices, and the fact that it has no surprising special cases and is frequently used (especially for computer-computer communication) means that it tends to be the most efficient choice too.

A common mistake is to implicitly use the default locale when producing output meant to be machine-readable. This tends to work on the developer's test devices (especially because so many developers use en_US), but fails when run on a device whose user is in a more complex locale.

For example, if you're formatting integers some locales will use non-ASCII decimal digits. As another example, if you're formatting floating-point numbers some locales will use ',' as the decimal point and '.' for digit grouping. That's correct for human-readable output, but likely to cause problems if presented to another computer (Double.ParseDouble(String) can't parse such a number, for example). You should also be wary of the String.ToLowerCase and String.ToUpperCase overloads that don't take a Locale: in Turkey, for example, the characters 'i' and 'I' won't be converted to 'I' and 'i'. This is the correct behavior for Turkish text (such as user input), but inappropriate for, say, HTTP headers.

[Android Documentation]

Requirements

Namespace: Java.Util
Assembly: Mono.Android (in Mono.Android.dll)
Assembly Versions: 0.0.0.0
Since: Added in API level 1

The members of Java.Util.Locale are listed below.

See Also: Object

Public Constructors

Constructs a new Locale using the specified language.
Constructs a new Locale using the specified language and country codes.
Constructs a new Locale using the specified language, country, and variant codes.

Public Properties

[read-only]
static
CanadaLocale. Locale constant for en_CA.
[read-only]
static
CanadaFrenchLocale. Locale constant for fr_CA.
[read-only]
static
ChinaLocale. Locale constant for zh_CN.
[read-only]
static
ChineseLocale. Locale constant for zh.
[read-only]
CountryString. Returns the country code for this locale, or "" if this locale doesn't correspond to a specific country.
static
DefaultLocale. Returns the user's preferred locale.
[read-only]
DisplayCountryString. Equivalent to getDisplayCountry(Locale.getDefault()).
[read-only]
DisplayLanguageString. Equivalent to getDisplayLanguage(Locale.getDefault()).
[read-only]
DisplayNameString. Equivalent to getDisplayName(Locale.getDefault()).
[read-only]
DisplayScriptString. Equivalent to getDisplayScript(Locale.getDefault()))
[read-only]
DisplayVariantString. Returns the full variant name in the default Locale for the variant code of this Locale.
[read-only]
static
EnglishLocale. Locale constant for en.
[read-only]
ExtensionKeysICollection<Java.Lang.Character>. Returns the set of BCP-47 extensions this locale contains.
[read-only]
static
FranceLocale. Locale constant for fr_FR.
[read-only]
static
FrenchLocale. Locale constant for fr.
[read-only]
static
GermanLocale. Locale constant for de.
[read-only]
static
GermanyLocale. Locale constant for de_DE.
[read-only]
ISO3CountryString. Returns the three-letter ISO 3166 country code which corresponds to the country code for this Locale.
[read-only]
ISO3LanguageString. Returns the three-letter ISO 639-2/T language code which corresponds to the language code for this Locale.
[read-only]
static
ItalianLocale. Locale constant for it.
[read-only]
static
ItalyLocale. Locale constant for it_IT.
[read-only]
static
JapanLocale. Locale constant for ja_JP.
[read-only]
static
JapaneseLocale. Locale constant for ja.
[read-only]
static
KoreaLocale. Locale constant for ko_KR.
[read-only]
static
KoreanLocale. Locale constant for ko.
[read-only]
LanguageString. Returns the language code for this Locale or the empty string if no language was set.
[read-only]
static
PrcLocale. Locale constant for zh_CN.
[read-only]
static
PrivateUseExtensionChar. BCP-47 extension identifier (or "singleton") for the private use extension.
[read-only]
static
RootLocale. Locale constant for the root locale.
[read-only]
ScriptString. Returns the script code for this Locale or an empty String if no script was set.
[read-only]
static
SimplifiedChineseLocale. Locale constant for zh_CN.
[read-only]
static
TaiwanLocale. Locale constant for zh_TW.
[read-only]
static
TraditionalChineseLocale. Locale constant for zh_TW.
[read-only]
static
UkLocale. Locale constant for en_GB.
[read-only]
UnicodeLocaleAttributesICollection<string>. Returns the set of unicode locale extension attributes this locale contains.
[read-only]
static
UnicodeLocaleExtensionChar. BCP-47 extension identifier (or "singleton") for the unicode locale extension.
[read-only]
UnicodeLocaleKeysICollection<string>. Returns the set of unicode locale extension keywords this locale contains.
[read-only]
static
UsLocale. Locale constant for en_US.
[read-only]
VariantString. Returns the variant code for this Locale or an empty String if no variant was set.

Protected Properties

[read-only]
override
ThresholdClassIntPtr. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
[read-only]
override
ThresholdTypeType. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Public Methods

Clone() : Object
Creates and returns a copy of this Object.
static
ForLanguageTag(String) : Locale
Returns a locale for a given BCP-47 language tag.
static
GetAvailableLocales() : Locale[]
Returns the system's installed locales.
GetDisplayCountry(Locale) : String
Returns the name of this locale's country, localized to locale.
GetDisplayLanguage(Locale) : String
Returns the name of this locale's language, localized to locale.
GetDisplayName(Locale) : String
Returns this locale's language name, country name, and variant, localized to locale.
GetDisplayScript(Locale) : String
Returns the name of this locale's script code, localized to Locale.
GetDisplayVariant(Locale) : String
Returns the full variant name in the specified Locale for the variant code of this Locale.
GetExtension(Char) : String
Returns the BCP-47 extension whose key is extensionKey, or null if this locale does not contain the extension.
static
GetISOCountries() : String[]
Returns an array of strings containing all the two-letter ISO 3166 country codes that can be used as the country code when constructing a Locale.
static
GetISOLanguages() : String[]
Returns an array of strings containing all the two-letter ISO 639-1 language codes that can be used as the language code when constructing a Locale.
GetUnicodeLocaleType(String) : String
Returns the type for the specified unicode locale extension key.
ToLanguageTag() : String
Returns a well formed BCP-47 language tag that identifies this locale.
override
ToString() : String
Returns the string representation of this Locale.