Skip to content

Most visited

Recently visited

navigation
Added in API level 1

Locale

public final class Locale
extends Object implements Cloneable, Serializable

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.

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:

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

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 (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.

Summary

Nested classes

class 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

public static final Locale CANADA

Locale constant for en_CA.

public static final Locale CANADA_FRENCH

Locale constant for fr_CA.

public static final Locale CHINA

Locale constant for zh_CN.

public static final Locale CHINESE

Locale constant for zh.

public static final Locale ENGLISH

Locale constant for en.

public static final Locale FRANCE

Locale constant for fr_FR.

public static final Locale FRENCH

Locale constant for fr.

public static final Locale GERMAN

Locale constant for de.

public static final Locale GERMANY

Locale constant for de_DE.

public static final Locale ITALIAN

Locale constant for it.

public static final Locale ITALY

Locale constant for it_IT.

public static final Locale JAPAN

Locale constant for ja_JP.

public static final Locale JAPANESE

Locale constant for ja.

public static final Locale KOREA

Locale constant for ko_KR.

public static final Locale KOREAN

Locale constant for ko.

public static final Locale PRC

Locale constant for zh_CN.

public static final Locale ROOT

Locale constant for the root locale.

public static final Locale SIMPLIFIED_CHINESE

Locale constant for zh_CN.

public static final Locale TAIWAN

Locale constant for zh_TW.

public static final Locale TRADITIONAL_CHINESE

Locale constant for zh_TW.

public static final Locale UK

Locale constant for en_GB.

public static final 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 forLanguageTag(String languageTag)

Returns a locale for a given BCP-47 language tag.

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()).

String getDisplayLanguage(Locale locale)

Returns the name of this locale's language, localized to locale.

final String getDisplayLanguage()

Equivalent to getDisplayLanguage(Locale.getDefault()).

final 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 getDisplayScript()

Equivalent to getDisplayScript(Locale.getDefault()))

String getDisplayScript(Locale locale)

Returns the name of this locale's script code, localized to Locale.

final 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 getExtension(char extensionKey)

Returns the BCP-47 extension whose key is extensionKey, or null if this locale does not contain the extension.

Set<Character> getExtensionKeys()

Returns the set of BCP-47 extensions this locale contains.

String getISO3Country()

Returns the three-letter ISO 3166 country code which corresponds to the country code for this Locale.

String getISO3Language()

Returns the three-letter ISO 639-2/T 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 3166 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 639-1 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 getScript()

Returns the script code for this Locale or an empty String if no script was set.

Set<String> getUnicodeLocaleAttributes()

Returns the set of unicode locale extension attributes this locale contains.

Set<String> getUnicodeLocaleKeys()

Returns the set of unicode locale extension keywords this locale contains.

String getUnicodeLocaleType(String keyWord)

Returns the type for the specified unicode locale extension key.

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 toLanguageTag()

Returns a well formed BCP-47 language tag that identifies this locale.

final String toString()

Returns the string representation of this Locale.

Inherited methods

From class java.lang.Object

Constants

PRIVATE_USE_EXTENSION

Added in API level 21
char PRIVATE_USE_EXTENSION

BCP-47 extension identifier (or "singleton") for the private use extension. See getExtension(char) and setExtension(char, String).

Constant Value: 120 (0x00000078)

UNICODE_LOCALE_EXTENSION

Added in API level 21
char UNICODE_LOCALE_EXTENSION

BCP-47 extension identifier (or "singleton") for the unicode locale extension. See getExtension(char) and setExtension(char, String).

Constant Value: 117 (0x00000075)

Fields

CANADA

Added in API level 1
Locale CANADA

Locale constant for en_CA.

CANADA_FRENCH

Added in API level 1
Locale CANADA_FRENCH

Locale constant for fr_CA.

CHINA

Added in API level 1
Locale CHINA

Locale constant for zh_CN.

CHINESE

Added in API level 1
Locale CHINESE

Locale constant for zh.

ENGLISH

Added in API level 1
Locale ENGLISH

Locale constant for en.

FRANCE

Added in API level 1
Locale FRANCE

Locale constant for fr_FR.

FRENCH

Added in API level 1
Locale FRENCH

Locale constant for fr.

GERMAN

Added in API level 1
Locale GERMAN

Locale constant for de.

GERMANY

Added in API level 1
Locale GERMANY

Locale constant for de_DE.

ITALIAN

Added in API level 1
Locale ITALIAN

Locale constant for it.

ITALY

Added in API level 1
Locale ITALY

Locale constant for it_IT.

JAPAN

Added in API level 1
Locale JAPAN

Locale constant for ja_JP.

JAPANESE

Added in API level 1
Locale JAPANESE

Locale constant for ja.

KOREA

Added in API level 1
Locale KOREA

Locale constant for ko_KR.

KOREAN

Added in API level 1
Locale KOREAN

Locale constant for ko.

PRC

Added in API level 1
Locale PRC

Locale constant for zh_CN.

ROOT

Added in API level 9
Locale ROOT

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

SIMPLIFIED_CHINESE

Added in API level 1
Locale SIMPLIFIED_CHINESE

Locale constant for zh_CN.

TAIWAN

Added in API level 1
Locale TAIWAN

Locale constant for zh_TW.

TRADITIONAL_CHINESE

Added in API level 1
Locale TRADITIONAL_CHINESE

Locale constant for zh_TW.

UK

Added in API level 1
Locale UK

Locale constant for en_GB.

US

Added in API level 1
Locale US

Locale constant for en_US.

Public constructors

Locale

Added in API level 1
Locale (String language)

Constructs a new Locale using the specified language.

Parameters
language String

Locale

Added in API level 1
Locale (String language, 
                String country)

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

Parameters
language String
country String

Locale

Added in API level 1
Locale (String language, 
                String country, 
                String variant)

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

Parameters
language String
country String
variant String

Public methods

clone

Added in API level 1
Object clone ()

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
Object a copy of this object.

equals

Added in API level 1
boolean equals (Object object)

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

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

forLanguageTag

Added in API level 21
Locale forLanguageTag (String languageTag)

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.

Parameters
languageTag String
Returns
Locale
Throws
NullPointerException if languageTag is null.

getAvailableLocales

Added in API level 1
Locale[] getAvailableLocales ()

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
Locale[]

See also:

getCountry

Added in API level 1
String getCountry ()

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

Returns
String

getDefault

Added in API level 1
Locale getDefault ()

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
Locale

getDisplayCountry

Added in API level 1
String getDisplayCountry (Locale locale)

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.

Parameters
locale Locale
Returns
String

getDisplayCountry

Added in API level 1
String getDisplayCountry ()

Equivalent to getDisplayCountry(Locale.getDefault()).

Returns
String

getDisplayLanguage

Added in API level 1
String getDisplayLanguage (Locale locale)

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

Parameters
locale Locale
Returns
String

getDisplayLanguage

Added in API level 1
String getDisplayLanguage ()

Equivalent to getDisplayLanguage(Locale.getDefault()).

Returns
String

getDisplayName

Added in API level 1
String getDisplayName ()

Equivalent to getDisplayName(Locale.getDefault()).

Returns
String

getDisplayName

Added in API level 1
String getDisplayName (Locale locale)

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).

Parameters
locale Locale
Returns
String

getDisplayScript

Added in API level 21
String getDisplayScript ()

Equivalent to getDisplayScript(Locale.getDefault()))

Returns
String

getDisplayScript

Added in API level 21
String getDisplayScript (Locale locale)

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().

Parameters
locale Locale
Returns
String

getDisplayVariant

Added in API level 1
String getDisplayVariant ()

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
String

getDisplayVariant

Added in API level 1
String getDisplayVariant (Locale locale)

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.

Parameters
locale Locale
Returns
String

getExtension

Added in API level 21
String getExtension (char extensionKey)

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).

Parameters
extensionKey char
Returns
String

getExtensionKeys

Added in API level 21
Set<Character> getExtensionKeys ()

Returns the set of BCP-47 extensions this locale contains. See the IETF BCP-47 specification (Section 2.2.6) for details.

Returns
Set<Character>

getISO3Country

Added in API level 1
String getISO3Country ()

Returns the three-letter ISO 3166 country code which corresponds to the country code for this Locale.

Returns
String
Throws
MissingResourceException if there's no 3-letter country code for this locale.

getISO3Language

Added in API level 1
String getISO3Language ()

Returns the three-letter ISO 639-2/T language code which corresponds to the language code for this Locale.

Returns
String
Throws
MissingResourceException if there's no 3-letter language code for this locale.

getISOCountries

Added in API level 1
String[] getISOCountries ()

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
String[]

getISOLanguages

Added in API level 1
String[] getISOLanguages ()

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
String[]

getLanguage

Added in API level 1
String getLanguage ()

Returns the language code for this Locale or the empty string if no language was set.

Returns
String

getScript

Added in API level 21
String getScript ()

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
String

getUnicodeLocaleAttributes

Added in API level 21
Set<String> getUnicodeLocaleAttributes ()

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
Set<String>

getUnicodeLocaleKeys

Added in API level 21
Set<String> getUnicodeLocaleKeys ()

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
Set<String>

getUnicodeLocaleType

Added in API level 21
String getUnicodeLocaleType (String keyWord)

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

Parameters
keyWord String
Returns
String

getVariant

Added in API level 1
String getVariant ()

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

Returns
String

hashCode

Added in API level 1
int hashCode ()

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.

Returns
int this object's hash code.

setDefault

Added in API level 1
void setDefault (Locale locale)

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.

Parameters
locale Locale

toLanguageTag

Added in API level 21
String toLanguageTag ()

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
String

toString

Added in API level 1
String toString ()

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
String a printable representation of this object.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.