public final class

Locale

extends Object
implements Serializable Cloneable
java.lang.Object
   ↳ java.util.Locale

Class Overview

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 ISO 639-1. The country codes are two-letter uppercase ISO country codes (such as "US") as defined by ISO 3166-1. 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 getDefault to get an appropriate locale for the user of the device you're running on, or 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:

cupcake/donut/eclair ICU 3.8 CLDR 1.5 Unicode 5.0
froyo ICU 4.2 CLDR 1.7 Unicode 5.1
gingerbread ICU 4.4 CLDR 1.8 Unicode 5.2

Be wary of the default locale

Note that there are many convenience methods that automatically use the default locale, but these may not be as convenient as you imagine. The default locale is appropriate for anything that involves presenting data to the user. You should use the user's date/time formats, number formats, rules for conversion to lowercase, and so on. 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 but fail when run on a device whose user is in a less conventional 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. That's correct for human-readable output, but likely to cause problems if presented to another computer (Double.parseDouble can't parse such a number, for example). The best choice for computer-readable output is usually Locale.US: this locale is guaranteed to be available on all devices, and the combination of no surprising behavior and frequent use (especially for computer-computer communication) means that it tends to be the most efficient choice too.

Summary

Constants
Locale CANADA Locale constant for en_CA.
Locale CANADA_FRENCH Locale constant for fr_CA.
Locale CHINA Locale constant for zh_CN.
Locale CHINESE Locale constant for zh.
Locale ENGLISH Locale constant for en.
Locale FRANCE Locale constant for fr_FR.
Locale FRENCH Locale constant for fr.
Locale GERMAN Locale constant for de.
Locale GERMANY Locale constant for de_DE.
Locale ITALIAN Locale constant for it.
Locale ITALY Locale constant for it_IT.
Locale JAPAN Locale constant for ja_JP.
Locale JAPANESE Locale constant for ja.
Locale KOREA Locale constant for ko_KR.
Locale KOREAN Locale constant for ko.
Locale PRC Locale constant for zh_CN.
Locale ROOT Locale constant for the root locale.
Locale SIMPLIFIED_CHINESE Locale constant for zh_CN.
Locale TAIWAN Locale constant for zh_TW.
Locale TRADITIONAL_CHINESE Locale constant for zh_TW.
Locale UK Locale constant for en_GB.
Locale US Locale constant for en_US.
Public Constructors
Locale(String language)
Constructs a new Locale using the specified language.
Locale(String language, String country)
Constructs a new Locale using the specified language and country codes.
Locale(String language, String country, String variant)
Constructs a new Locale using the specified language, country, and variant codes.
Public Methods
Object clone()
Creates and returns a copy of this Object.
boolean equals(Object object)
Returns true if object is a locale with the same language, country and variant.
static Locale[] getAvailableLocales()
Returns the system's installed locales.
String getCountry()
Returns the country code for this locale, or "" if this locale doesn't correspond to a specific country.
static Locale getDefault()
Returns the user's preferred locale.
String getDisplayCountry(Locale locale)
Returns the name of this locale's country, localized to locale.
final String getDisplayCountry()
Equivalent to getDisplayCountry(Locale.getDefault()).
final String getDisplayLanguage()
Equivalent to getDisplayLanguage(Locale.getDefault()).
String getDisplayLanguage(Locale locale)
Returns the name of this locale's language, localized to locale.
String getDisplayName(Locale locale)
Returns this locale's language name, country name, and variant, localized to locale.
final String getDisplayName()
Equivalent to getDisplayName(Locale.getDefault()).
final String getDisplayVariant()
Gets the full variant name in the default Locale for the variant code of this Locale.
String getDisplayVariant(Locale locale)
Gets the full variant name in the specified Locale for the variant code of this Locale.
String getISO3Country()
Gets the three letter ISO country code which corresponds to the country code for this Locale.
String getISO3Language()
Gets the three letter ISO language code which corresponds to the language code for this Locale.
static String[] getISOCountries()
Gets the list of two letter ISO country codes which can be used as the country code for a Locale.
static String[] getISOLanguages()
Gets the list of two letter ISO language codes which can be used as the language code for a Locale.
String getLanguage()
Gets the language code for this Locale or the empty string of no language was set.
String getVariant()
Gets the variant code for this Locale or an empty String if no variant was set.
synchronized int hashCode()
Returns an integer hash code for the receiver.
synchronized static void setDefault(Locale locale)
Overrides the default locale.
final String toString()
Returns the string representation of this Locale.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final Locale CANADA

Since: API Level 1

Locale constant for en_CA.

public static final Locale CANADA_FRENCH

Since: API Level 1

Locale constant for fr_CA.

public static final Locale CHINA

Since: API Level 1

Locale constant for zh_CN.

public static final Locale CHINESE

Since: API Level 1

Locale constant for zh.

public static final Locale ENGLISH

Since: API Level 1

Locale constant for en.

public static final Locale FRANCE

Since: API Level 1

Locale constant for fr_FR.

public static final Locale FRENCH

Since: API Level 1

Locale constant for fr.

public static final Locale GERMAN

Since: API Level 1

Locale constant for de.

public static final Locale GERMANY

Since: API Level 1

Locale constant for de_DE.

public static final Locale ITALIAN

Since: API Level 1

Locale constant for it.

public static final Locale ITALY

Since: API Level 1

Locale constant for it_IT.

public static final Locale JAPAN

Since: API Level 1

Locale constant for ja_JP.

public static final Locale JAPANESE

Since: API Level 1

Locale constant for ja.

public static final Locale KOREA

Since: API Level 1

Locale constant for ko_KR.

public static final Locale KOREAN

Since: API Level 1

Locale constant for ko.

public static final Locale PRC

Since: API Level 1

Locale constant for zh_CN.

public static final Locale ROOT

Since: API Level 9

Locale constant for the root locale. The root locale has an empty language, country, and variant.

public static final Locale SIMPLIFIED_CHINESE

Since: API Level 1

Locale constant for zh_CN.

public static final Locale TAIWAN

Since: API Level 1

Locale constant for zh_TW.

public static final Locale TRADITIONAL_CHINESE

Since: API Level 1

Locale constant for zh_TW.

public static final Locale UK

Since: API Level 1

Locale constant for en_GB.

public static final Locale US

Since: API Level 1

Locale constant for en_US.

Public Constructors

public Locale (String language)

Since: API Level 1

Constructs a new Locale using the specified language.

public Locale (String language, String country)

Since: API Level 1

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

public Locale (String language, String country, String variant)

Since: API Level 1

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

Public Methods

public Object clone ()

Since: API Level 1

Creates and returns a copy of this Object. The default implementation returns a so-called "shallow" copy: It creates a new instance of the same class and then copies the field values (including object references) from this instance to the new instance. A "deep" copy, in contrast, would also recursively clone nested objects. A subclass that needs to implement this kind of cloning should call super.clone() to create the new instance and then create deep copies of the nested, mutable objects.

Returns
  • a copy of this object.

public boolean equals (Object object)

Since: API Level 1

Returns true if object is a locale with the same language, country and variant.

Parameters
object the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object; false otherwise.

public static Locale[] getAvailableLocales ()

Since: API Level 1

Returns the system's installed locales. This array always includes Locale.US, and usually several others. Most locale-sensitive classes offer their own getAvailableLocales method, which should be preferred over this general purpose method.

public String getCountry ()

Since: API Level 1

Returns the country code for this locale, or "" if this locale doesn't correspond to a specific country.

public static Locale getDefault ()

Since: API Level 1

Returns the user's preferred locale. This may have been overridden for this process with setDefault(Locale).

Since the user's locale changes dynamically, avoid caching this value. Instead, use this method to look it up for each use.

public String getDisplayCountry (Locale locale)

Since: API Level 1

Returns the name of this locale's country, localized to locale. Returns the empty string if this locale does not correspond to a specific country.

public final String getDisplayCountry ()

Since: API Level 1

Equivalent to getDisplayCountry(Locale.getDefault()).

public final String getDisplayLanguage ()

Since: API Level 1

Equivalent to getDisplayLanguage(Locale.getDefault()).

public String getDisplayLanguage (Locale locale)

Since: API Level 1

Returns the name of this locale's language, localized to locale. If the language name is unknown, the language code is returned.

public String getDisplayName (Locale locale)

Since: API Level 1

Returns this locale's language name, country name, and variant, localized to locale. The exact output form depends on whether this locale corresponds to a specific language, country and variant, such as: English, English (United States), English (United States,Computer), anglais (États-Unis), anglais (États-Unis,informatique).

public final String getDisplayName ()

Since: API Level 1

Equivalent to getDisplayName(Locale.getDefault()).

public final String getDisplayVariant ()

Since: API Level 1

Gets the full variant name in the default Locale for the variant code of this Locale. If there is no matching variant name, the variant code is returned.

Returns
  • a variant name.

public String getDisplayVariant (Locale locale)

Since: API Level 1

Gets the full variant name in the specified Locale for the variant code of this Locale. If there is no matching variant name, the variant code is returned.

Parameters
locale the Locale for which the display name is retrieved.
Returns
  • a variant name.

public String getISO3Country ()

Since: API Level 1

Gets the three letter ISO country code which corresponds to the country code for this Locale.

Returns
  • a three letter ISO language code.
Throws
MissingResourceException if there is no matching three letter ISO country code.

public String getISO3Language ()

Since: API Level 1

Gets the three letter ISO language code which corresponds to the language code for this Locale.

Returns
  • a three letter ISO language code.
Throws
MissingResourceException if there is no matching three letter ISO language code.

public static String[] getISOCountries ()

Since: API Level 1

Gets the list of two letter ISO country codes which can be used as the country code for a Locale.

Returns
  • an array of strings.

public static String[] getISOLanguages ()

Since: API Level 1

Gets the list of two letter ISO language codes which can be used as the language code for a Locale.

Returns
  • an array of strings.

public String getLanguage ()

Since: API Level 1

Gets the language code for this Locale or the empty string of no language was set.

Returns
  • a language code.

public String getVariant ()

Since: API Level 1

Gets the variant code for this Locale or an empty String if no variant was set.

Returns
  • a variant code.

public synchronized int hashCode ()

Since: API Level 1

Returns an integer hash code for the receiver. Objects which are equal return the same value for this method.

Returns
  • the receiver's hash.
See Also

public static synchronized void setDefault (Locale locale)

Since: API Level 1

Overrides the default locale. This does not affect system configuration, and attempts to override the system-provided default locale may themselves be overridden by actual changes to the system configuration. Code that calls this method is usually incorrect, and should be fixed by passing the appropriate locale to each locale-sensitive method that's called.

public final String toString ()

Since: API Level 1

Returns the string representation of this Locale. It consists of the language code, country code and variant separated by underscores. If the language is missing the string begins with an underscore. If the country is missing there are 2 underscores between the language and the variant. The variant cannot stand alone without a language and/or country code: in this case this method would return the empty string.

Examples: "en", "en_US", "_US", "en__POSIX", "en_US_POSIX"

Returns
  • the string representation of this Locale.