public final class Locale extends Object implements Cloneable, Serializable
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/honeycomb | ICU 4.4 | CLDR 1.8 | Unicode 5.2 |
ice cream sandwich | ICU 4.6 | CLDR 1.9 | Unicode 6.0 |
jelly bean | ICU 4.8 | CLDR 2.0 | Unicode 6.0 |
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(java.lang.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.
Modifier and Type | Field and Description |
---|---|
static Locale |
CANADA
Locale constant for en_CA.
|
static Locale |
CANADA_FRENCH
Locale constant for fr_CA.
|
static Locale |
CHINA
Locale constant for zh_CN.
|
static Locale |
CHINESE
Locale constant for zh.
|
static Locale |
ENGLISH
Locale constant for en.
|
static Locale |
FRANCE
Locale constant for fr_FR.
|
static Locale |
FRENCH
Locale constant for fr.
|
static Locale |
GERMAN
Locale constant for de.
|
static Locale |
GERMANY
Locale constant for de_DE.
|
static Locale |
ITALIAN
Locale constant for it.
|
static Locale |
ITALY
Locale constant for it_IT.
|
static Locale |
JAPAN
Locale constant for ja_JP.
|
static Locale |
JAPANESE
Locale constant for ja.
|
static Locale |
KOREA
Locale constant for ko_KR.
|
static Locale |
KOREAN
Locale constant for ko.
|
static Locale |
PRC
Locale constant for zh_CN.
|
static Locale |
ROOT
Locale constant for the root locale.
|
static Locale |
SIMPLIFIED_CHINESE
Locale constant for zh_CN.
|
static Locale |
TAIWAN
Locale constant for zh_TW.
|
static Locale |
TRADITIONAL_CHINESE
Locale constant for zh_TW.
|
static Locale |
UK
Locale constant for en_GB.
|
static Locale |
US
Locale constant for en_US.
|
Constructor and Description |
---|
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. |
Modifier and Type | Method and Description |
---|---|
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()
Equivalent to
getDisplayCountry(Locale.getDefault()) . |
String |
getDisplayCountry(Locale locale)
Returns the name of this locale's country, localized to
locale . |
String |
getDisplayLanguage()
Equivalent to
getDisplayLanguage(Locale.getDefault()) . |
String |
getDisplayLanguage(Locale locale)
Returns the name of this locale's language, localized to
locale . |
String |
getDisplayName()
Equivalent to
getDisplayName(Locale.getDefault()) . |
String |
getDisplayName(Locale locale)
Returns this locale's language name, country name, and variant, localized
to
locale . |
String |
getDisplayVariant()
Returns the full variant name in the default
Locale for the variant code of
this Locale . |
String |
getDisplayVariant(Locale locale)
Returns the full variant name in the specified
Locale for the variant code
of this Locale . |
String |
getISO3Country()
Returns the three letter ISO country code which corresponds to the country
code for this
Locale . |
String |
getISO3Language()
Returns the three letter ISO language code which corresponds to the language
code for this
Locale . |
static String[] |
getISOCountries()
Returns an array of strings containing all the two-letter ISO country codes that can be
used as the country code when constructing a
Locale . |
static String[] |
getISOLanguages()
Returns an array of strings containing all the two-letter ISO language codes that can be
used as the language code when constructing a
Locale . |
String |
getLanguage()
Returns the language code for this
Locale or the empty string if no language
was set. |
String |
getVariant()
Returns the variant code for this
Locale or an empty String if no variant
was set. |
int |
hashCode()
Returns an integer hash code for this object.
|
static void |
setDefault(Locale locale)
Overrides the default locale.
|
String |
toString()
Returns the string representation of this
Locale . |
public static final Locale CANADA
public static final Locale CANADA_FRENCH
public static final Locale CHINA
public static final Locale CHINESE
public static final Locale ENGLISH
public static final Locale FRANCE
public static final Locale FRENCH
public static final Locale GERMAN
public static final Locale GERMANY
public static final Locale ITALIAN
public static final Locale ITALY
public static final Locale JAPAN
public static final Locale JAPANESE
public static final Locale KOREA
public static final Locale KOREAN
public static final Locale PRC
public static final Locale ROOT
public static final Locale SIMPLIFIED_CHINESE
public static final Locale TAIWAN
public static final Locale TRADITIONAL_CHINESE
public static final Locale UK
public static final Locale US
public Locale(String language)
Locale
using the specified language.public Locale(String language, String country)
Locale
using the specified language and country codes.public Object clone()
Object
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.public boolean equals(Object object)
object
is a locale with the same language,
country and variant.equals
in class Object
object
- the object to compare this instance with.true
if the specified object is equal to this Object
; false
otherwise.Object.hashCode()
public static Locale[] getAvailableLocales()
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()
""
if this locale
doesn't correspond to a specific country.public static Locale getDefault()
setDefault(java.util.Locale)
.
Since the user's locale changes dynamically, avoid caching this value. Instead, use this method to look it up for each use.
public final String getDisplayCountry()
getDisplayCountry(Locale.getDefault())
.public String getDisplayCountry(Locale locale)
locale
.
Returns the empty string if this locale does not correspond to a specific
country.public final String getDisplayLanguage()
getDisplayLanguage(Locale.getDefault())
.public String getDisplayLanguage(Locale locale)
locale
.
If the language name is unknown, the language code is returned.public final String getDisplayName()
getDisplayName(Locale.getDefault())
.public String getDisplayName(Locale locale)
locale
. The exact output form depends on whether this locale
corresponds to a specific language, country and variant.
For example:
new Locale("en").getDisplayName(Locale.US)
-> English
new Locale("en", "US").getDisplayName(Locale.US)
-> English (United States)
new Locale("en", "US", "POSIX").getDisplayName(Locale.US)
-> English (United States,Computer)
new Locale("en").getDisplayName(Locale.FRANCE)
-> anglais
new Locale("en", "US").getDisplayName(Locale.FRANCE)
-> anglais (États-Unis)
new Locale("en", "US", "POSIX").getDisplayName(Locale.FRANCE)
-> anglais (États-Unis,informatique)
.
public final String getDisplayVariant()
Locale
for the variant code of
this Locale
. If there is no matching variant name, the variant code is
returned.public String getDisplayVariant(Locale locale)
Locale
for the variant code
of this Locale
. If there is no matching variant name, the variant code is
returned.public String getISO3Country()
Locale
.public String getISO3Language()
Locale
.public static String[] getISOCountries()
Locale
.public static String[] getISOLanguages()
Locale
.public String getLanguage()
Locale
or the empty string if no language
was set.public String getVariant()
Locale
or an empty String
if no variant
was set.public int hashCode()
Object
Object.equals(java.lang.Object)
returns true
must return
the same hash code value. This means that subclasses of Object
usually override both methods or neither method.
Note that hash values must not change over time unless information used in equals comparisons also changes.
See Writing a correct
hashCode
method
if you intend implementing your own hashCode
method.
hashCode
in class Object
Object.equals(java.lang.Object)
public static void setDefault(Locale locale)
public final String toString()
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"