| java.lang.Object | |
| ↳ | java.util.Locale |
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.
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.
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 | CLDR 1.5 | Unicode 5.0 |
| Android 2.2 (Froyo) | ICU 4.2 | CLDR 1.7 | Unicode 5.1 |
| Android 2.3 (Gingerbread)/Android 3.0 (Honeycomb) | ICU 4.4 | CLDR 1.8 | Unicode 5.2 |
| Android 4.0 (Ice Cream Sandwich) | ICU 4.6 | CLDR 1.9 | Unicode 6.0 |
| Android 4.1 (Jelly Bean) | ICU 4.8 | CLDR 2.0 | Unicode 6.0 |
| Android 4.3 (Jelly Bean MR2) | ICU 50 | CLDR 22.1 | Unicode 6.2 |
| Android 4.4 (KitKat) | ICU 51 | CLDR 23 | Unicode 6.2 |
| Android 5.0 (Lollipop) | ICU 53 | CLDR 25 | Unicode 6.3 |
| Android 6.0 (Marshmallow) | ICU 55.1 | CLDR 27.0.1 | Unicode 7.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 (parseDouble(String) can't parse such a number, for example).
You should also be wary of the toLowerCase() and
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.
| Nested Classes | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Locale.Builder |
A class that helps construct Locale instances.
|
||||||||||
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| char | PRIVATE_USE_EXTENSION | BCP-47 extension identifier (or "singleton") for the private use extension. | |||||||||
| char | UNICODE_LOCALE_EXTENSION | BCP-47 extension identifier (or "singleton") for the unicode locale extension. | |||||||||
| Fields | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| CANADA | Locale constant for en_CA. | ||||||||||
| CANADA_FRENCH | Locale constant for fr_CA. | ||||||||||
| CHINA | Locale constant for zh_CN. | ||||||||||
| CHINESE | Locale constant for zh. | ||||||||||
| ENGLISH | Locale constant for en. | ||||||||||
| FRANCE | Locale constant for fr_FR. | ||||||||||
| FRENCH | Locale constant for fr. | ||||||||||
| GERMAN | Locale constant for de. | ||||||||||
| GERMANY | Locale constant for de_DE. | ||||||||||
| ITALIAN | Locale constant for it. | ||||||||||
| ITALY | Locale constant for it_IT. | ||||||||||
| JAPAN | Locale constant for ja_JP. | ||||||||||
| JAPANESE | Locale constant for ja. | ||||||||||
| KOREA | Locale constant for ko_KR. | ||||||||||
| KOREAN | Locale constant for ko. | ||||||||||
| PRC | Locale constant for zh_CN. | ||||||||||
| ROOT | Locale constant for the root locale. | ||||||||||
| SIMPLIFIED_CHINESE | Locale constant for zh_CN. | ||||||||||
| TAIWAN | Locale constant for zh_TW. | ||||||||||
| TRADITIONAL_CHINESE | Locale constant for zh_TW. | ||||||||||
| UK | Locale constant for en_GB. | ||||||||||
| US | Locale constant for en_US. | ||||||||||
| 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 Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Creates and returns a copy of this
Object.
| |||||||||||
Returns true if
object is a locale with the same language,
country and variant.
| |||||||||||
Returns a locale for a given BCP-47 language tag.
| |||||||||||
Returns the system's installed locales.
| |||||||||||
Returns the country code for this locale, or
"" if this locale
doesn't correspond to a specific country.
| |||||||||||
Returns the user's preferred locale.
| |||||||||||
Returns the name of this locale's country, localized to
locale.
| |||||||||||
Equivalent to
getDisplayCountry(Locale.getDefault()).
| |||||||||||
Returns the name of this locale's language, localized to
locale.
| |||||||||||
Equivalent to
getDisplayLanguage(Locale.getDefault()).
| |||||||||||
Equivalent to
getDisplayName(Locale.getDefault()).
| |||||||||||
Returns this locale's language name, country name, and variant, localized
to
locale.
| |||||||||||
Equivalent to
getDisplayScript(Locale.getDefault()))
| |||||||||||
Returns the name of this locale's script code, localized to
Locale.
| |||||||||||
Returns the full variant name in the default
Locale for the variant code of
this Locale.
| |||||||||||
Returns the full variant name in the specified
Locale for the variant code
of this Locale.
| |||||||||||
Returns the BCP-47 extension whose key is
extensionKey, or null
if this locale does not contain the extension.
| |||||||||||
Returns the set of BCP-47 extensions this locale contains.
| |||||||||||
Returns the three-letter ISO 3166 country code which corresponds to the country
code for this
Locale.
| |||||||||||
Returns the three-letter ISO 639-2/T language code which corresponds to the language
code for this
Locale.
| |||||||||||
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.
| |||||||||||
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.
| |||||||||||
Returns the language code for this
Locale or the empty string if no language
was set.
| |||||||||||
Returns the script code for this
Locale or an empty String if no script
was set.
| |||||||||||
Returns the set of unicode locale extension attributes this locale contains.
| |||||||||||
Returns the set of unicode locale extension keywords this locale contains.
| |||||||||||
Returns the
type for the specified unicode locale extension key.
| |||||||||||
Returns the variant code for this
Locale or an empty String if no variant
was set.
| |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Overrides the default locale.
| |||||||||||
Returns a well formed BCP-47 language tag that identifies this locale.
| |||||||||||
Returns the string representation of this
Locale.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
BCP-47 extension identifier (or "singleton") for the private
use extension.
See getExtension(char) and setExtension(char, String).
BCP-47 extension identifier (or "singleton") for the unicode locale extension.
See getExtension(char) and setExtension(char, String).
Locale constant for the root locale. The root locale has an empty language, country, and variant.
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.
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 true if object is a locale with the same language,
country and variant.
| object | the object to compare this instance with. |
|---|
Developers
true if the specified object is equal to this Object; false otherwise.Returns a locale for a given BCP-47 language tag. This method is more
lenient than setLanguageTag(String). For a given language tag, parsing
will proceed up to the first malformed subtag. All subsequent tags are discarded.
Note that language tags use - rather than _, for example en-US.
| NullPointerException | if languageTag is null. |
|---|
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.
Returns the country code for this locale, or "" if this locale
doesn't correspond to a specific country.
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.
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.
Equivalent to getDisplayCountry(Locale.getDefault()).
Returns the name of this locale's language, localized to locale.
If the language name is unknown, the language code is returned.
Equivalent to getDisplayLanguage(Locale.getDefault()).
Equivalent to getDisplayName(Locale.getDefault()).
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, script, 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)
Locale.fromLanguageTag("zh-Hant-CN").getDisplayName(Locale.US) -> Chinese (Traditional Han,China)
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).
Equivalent to getDisplayScript(Locale.getDefault()))
Returns the name of this locale's script code, localized to Locale. If the
script code is unknown, the return value of this method is the same as that of
getScript().
Returns 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 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.
Returns the BCP-47 extension whose key is extensionKey, or null
if this locale does not contain the extension.
Individual Keywords and attributes for the unicode
locale extension can be fetched using getUnicodeLocaleAttributes(),
getUnicodeLocaleKeys() and getUnicodeLocaleType(String).
Returns the set of BCP-47 extensions this locale contains. See the IETF BCP-47 specification (Section 2.2.6) for details.
Returns the three-letter ISO 3166 country code which corresponds to the country
code for this Locale.
| MissingResourceException | if there's no 3-letter country code for this locale. |
|---|
Returns the three-letter ISO 639-2/T language code which corresponds to the language
code for this Locale.
| MissingResourceException | if there's no 3-letter language code for this locale. |
|---|
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.
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.
Returns the language code for this Locale or the empty string if no language
was set.
Returns the script code for this Locale or an empty String if no script
was set.
If set, the script code will be a title cased string of length 4, as per the ISO 15924
specification.
Returns the set of unicode locale extension attributes this locale contains.
For more information about attributes, see addUnicodeLocaleAttribute(String)
and Unicode Technical Standard #35
Returns the set of unicode locale extension keywords this locale contains.
For more information about types and keywords, see setUnicodeLocaleKeyword(String, String)
and Unicode Technical Standard #35
Returns the type for the specified unicode locale extension key.
For more information about types and keywords, see setUnicodeLocaleKeyword(String, String)
and Unicode Technical Standard #35
Returns the variant code for this Locale or an empty String if no variant
was set.
Returns an integer hash code for this object. By contract, any two
objects for which equals(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.
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.
Returns a well formed BCP-47 language tag that identifies this locale.
Note that this locale itself might consist of ill formed fields, since the
public Locale constructors do not perform validity checks to maintain
backwards compatibility. When this is the case, this method will either replace
ill formed fields with standard BCP-47 subtags (For eg. "und" (undetermined)
for invalid languages) or omit them altogether.
Additionally, ill formed variants will result in the remainder of the tag
(both variants and extensions) being moved to the private use extension,
where they will appear after a subtag whose value is "lvariant".
It's also important to note that the BCP-47 tag is well formed in the sense
that it is unambiguously parseable into its specified components. We do not
require that any of the components are registered with the applicable registries.
For example, we do not require scripts to be a registered ISO 15924 scripts or
languages to appear in the ISO-639-2 code list.
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"