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 is true even if you construct your own Locale object, not just of instances returned by the various lookup methods.

Just because you can create a Locale doesn't mean that it makes much sense. Imagine "de_US" for German as spoken in the US, for example. 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 sp_US (English and Spanish, as spoken in the US), but not necessarily en_GB or sp_SP (English as spoken in Great Britain or Spanish as spoken in Spain), for example. The opposite may well be true for a device sold in Europe. (This limitation even affects those locales pre-defined as constants in this class.)

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

See Also

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 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()
Returns a new Locale with the same language, country and variant codes as this Locale.
boolean equals(Object object)
Compares the specified object to this Locale and returns whether they are equal.
static Locale[] getAvailableLocales()
Gets the list of installed Locales.
String getCountry()
Gets the country code for this Locale or an empty string of no country was set.
static Locale getDefault()
Gets the default Locale.
String getDisplayCountry(Locale locale)
Gets the full country name in the specified Locale for the country code of this Locale.
final String getDisplayCountry()
Gets the full country name in the default Locale for the country code of this Locale.
final String getDisplayLanguage()
Gets the full language name in the default Locale for the language code of this Locale.
String getDisplayLanguage(Locale locale)
Gets the full language name in the specified Locale for the language code of this Locale.
final String getDisplayName()
Gets the full language, country, and variant names in the default Locale for the codes of this Locale.
String getDisplayName(Locale locale)
Gets the full language, country, and variant names in the specified Locale for the codes of this Locale.
String getDisplayVariant(Locale locale)
Gets the full variant name in the specified Locale for the variant code of this Locale.
final String getDisplayVariant()
Gets the full variant name in the default 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)
Sets the default Locale to the specified 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 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.

Parameters
language the language this Locale represents.

public Locale (String language, String country)

Since: API Level 1

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

Parameters
language the language this Locale represents.
country the country this Locale represents.

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

Since: API Level 1

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

Parameters
language the language this Locale represents.
country the country this Locale represents.
variant the variant this Locale represents.
Throws
NullPointerException if language, country, or variant is null.

Public Methods

public Object clone ()

Since: API Level 1

Returns a new Locale with the same language, country and variant codes as this Locale.

Returns
  • a shallow copy of this Locale.
See Also

public boolean equals (Object object)

Since: API Level 1

Compares the specified object to this Locale and returns whether they are equal. The object must be an instance of Locale and have the same language, country and variant.

Parameters
object the object to compare with this object.
Returns
  • true if the specified object is equal to this Locale, false otherwise.
See Also

public static Locale[] getAvailableLocales ()

Since: API Level 1

Gets the list of installed Locales. At least a Locale that is equal to Locale.US must be contained in this array.

Returns
  • an array of Locales.

public String getCountry ()

Since: API Level 1

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

Returns
  • a country code.

public static Locale getDefault ()

Since: API Level 1

Gets the default Locale.

Returns
  • the default Locale.

public String getDisplayCountry (Locale locale)

Since: API Level 1

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

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

public final String getDisplayCountry ()

Since: API Level 1

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

Returns
  • a country name.

public final String getDisplayLanguage ()

Since: API Level 1

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

Returns
  • a language name.

public String getDisplayLanguage (Locale locale)

Since: API Level 1

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

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

public final String getDisplayName ()

Since: API Level 1

Gets the full language, country, and variant names in the default Locale for the codes of this Locale.

Returns
  • a Locale name.

public String getDisplayName (Locale locale)

Since: API Level 1

Gets the full language, country, and variant names in the specified Locale for the codes of this Locale.

Parameters
locale the Locale for which the display name is retrieved.
Returns
  • a Locale 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 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 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

Sets the default Locale to the specified Locale.

Parameters
locale the new default Locale.
Throws
SecurityException if there is a SecurityManager in place which does not allow this operation.

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.