Class Locale
- java.lang.Object
-
- java.util.Locale
-
- All Implemented Interfaces:
Serializable,Cloneable
public final class Locale extends Object implements Cloneable, Serializable
Localerepresents 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
Localeobject, not just for instances returned by the various lookup methods.Available locales
This class' constructors do no error checking. You can create a
Localefor 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, orgetAvailableLocales()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.spiorjava.util.spimechanisms) 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 (Double.parseDouble(java.lang.String)can't parse such a number, for example). You should also be wary of theString.toLowerCase()andString.toUpperCase()overloads that don't take aLocale: 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.- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classLocale.BuilderA class that helps constructLocaleinstances.
-
Field Summary
Fields Modifier and Type Field Description static LocaleCANADALocale constant for en_CA.static LocaleCANADA_FRENCHLocale constant for fr_CA.static LocaleCHINALocale constant for zh_CN.static LocaleCHINESELocale constant for zh.static LocaleENGLISHLocale constant for en.static LocaleFRANCELocale constant for fr_FR.static LocaleFRENCHLocale constant for fr.static LocaleGERMANLocale constant for de.static LocaleGERMANYLocale constant for de_DE.static LocaleITALIANLocale constant for it.static LocaleITALYLocale constant for it_IT.static LocaleJAPANLocale constant for ja_JP.static LocaleJAPANESELocale constant for ja.static LocaleKOREALocale constant for ko_KR.static LocaleKOREANLocale constant for ko.static LocalePRCLocale constant for zh_CN.static charPRIVATE_USE_EXTENSIONBCP-47 extension identifier (or "singleton") for the private use extension.static LocaleROOTLocale constant for the root locale.static LocaleSIMPLIFIED_CHINESELocale constant for zh_CN.static LocaleTAIWANLocale constant for zh_TW.static LocaleTRADITIONAL_CHINESELocale constant for zh_TW.static LocaleUKLocale constant for en_GB.static charUNICODE_LOCALE_EXTENSIONBCP-47 extension identifier (or "singleton") for the unicode locale extension.static LocaleUSLocale constant for en_US.
-
Constructor Summary
Constructors Constructor Description Locale(String language)Constructs a newLocaleusing the specified language.Locale(String language, String country)Constructs a newLocaleusing the specified language and country codes.Locale(String language, String country, String variant)Constructs a newLocaleusing the specified language, country, and variant codes.Locale(String language, String country, String variant, String scriptCode, Set<String> unicodeAttributes, Map<String,String> unicodeKeywords, Map<Character,String> extensions, boolean hasValidatedFields)Required by libcore.icu.ICU.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static StringadjustLanguageCode(String languageCode)Objectclone()Creates and returns a copy of thisObject.booleanequals(Object object)Returns true ifobjectis a locale with the same language, country and variant.static LocaleforLanguageTag(String languageTag)Returns a locale for a given BCP-47 language tag.static Locale[]getAvailableLocales()Returns the system's installed locales.StringgetCountry()Returns the country code for this locale, or""if this locale doesn't correspond to a specific country.static LocalegetDefault()Returns the user's preferred locale.static LocalegetDefaultLocaleFromSystemProperties()Returns the default locale from system properties.StringgetDisplayCountry()Equivalent togetDisplayCountry(Locale.getDefault()).StringgetDisplayCountry(Locale locale)Returns the name of this locale's country, localized tolocale.StringgetDisplayLanguage()Equivalent togetDisplayLanguage(Locale.getDefault()).StringgetDisplayLanguage(Locale locale)Returns the name of this locale's language, localized tolocale.StringgetDisplayName()Equivalent togetDisplayName(Locale.getDefault()).StringgetDisplayName(Locale locale)Returns this locale's language name, country name, and variant, localized tolocale.StringgetDisplayScript()Equivalent togetDisplayScript(Locale.getDefault()))StringgetDisplayScript(Locale locale)Returns the name of this locale's script code, localized toLocale.StringgetDisplayVariant()Returns the full variant name in the defaultLocalefor the variant code of thisLocale.StringgetDisplayVariant(Locale locale)Returns the full variant name in the specifiedLocalefor the variant code of thisLocale.StringgetExtension(char extensionKey)Returns the BCP-47 extension whose key isextensionKey, ornullif this locale does not contain the extension.Set<Character>getExtensionKeys()Returns the set of BCP-47 extensions this locale contains.StringgetISO3Country()Returns the three-letter ISO 3166 country code which corresponds to the country code for thisLocale.StringgetISO3Language()Returns the three-letter ISO 639-2/T language code which corresponds to the language code for thisLocale.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 aLocale.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 aLocale.StringgetLanguage()Returns the language code for thisLocaleor the empty string if no language was set.StringgetScript()Returns the script code for thisLocaleor an emptyStringif 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.StringgetUnicodeLocaleType(String keyWord)Returns thetypefor the specified unicode locale extensionkey.StringgetVariant()Returns the variant code for thisLocaleor an emptyStringif no variant was set.inthashCode()Returns an integer hash code for this object.static voidparseSerializedExtensions(String extString, Map<Character,String> outputMap)Visible for testing.static voidparseUnicodeExtension(String[] subtags, Map<String,String> keywords, Set<String> attributes)This extension is described by http://www.unicode.org/reports/tr35/#RFC5234 unicode_locale_extensions = sep "u" (1*(sep keyword) / 1*(sep attribute) *(sep keyword)).static StringserializeExtensions(Map<Character,String> extensionsMap)The serialized form for extensions is straightforward.static voidsetDefault(Locale locale)Overrides the default locale.StringtoLanguageTag()Returns a well formed BCP-47 language tag that identifies this locale.StringtoString()Returns the string representation of thisLocale.
-
-
-
Field Detail
-
CANADA
public static final Locale CANADA
Locale constant for en_CA.
-
CANADA_FRENCH
public static final Locale CANADA_FRENCH
Locale constant for fr_CA.
-
CHINA
public static final Locale CHINA
Locale constant for zh_CN.
-
CHINESE
public static final Locale CHINESE
Locale constant for zh.
-
ENGLISH
public static final Locale ENGLISH
Locale constant for en.
-
FRANCE
public static final Locale FRANCE
Locale constant for fr_FR.
-
FRENCH
public static final Locale FRENCH
Locale constant for fr.
-
GERMAN
public static final Locale GERMAN
Locale constant for de.
-
GERMANY
public static final Locale GERMANY
Locale constant for de_DE.
-
ITALIAN
public static final Locale ITALIAN
Locale constant for it.
-
ITALY
public static final Locale ITALY
Locale constant for it_IT.
-
JAPAN
public static final Locale JAPAN
Locale constant for ja_JP.
-
JAPANESE
public static final Locale JAPANESE
Locale constant for ja.
-
KOREA
public static final Locale KOREA
Locale constant for ko_KR.
-
KOREAN
public static final Locale KOREAN
Locale constant for ko.
-
PRC
public static final Locale PRC
Locale constant for zh_CN.
-
ROOT
public static final Locale ROOT
Locale constant for the root locale. The root locale has an empty language, country, and variant.- Since:
- 1.6
-
SIMPLIFIED_CHINESE
public static final Locale SIMPLIFIED_CHINESE
Locale constant for zh_CN.
-
TAIWAN
public static final Locale TAIWAN
Locale constant for zh_TW.
-
TRADITIONAL_CHINESE
public static final Locale TRADITIONAL_CHINESE
Locale constant for zh_TW.
-
UK
public static final Locale UK
Locale constant for en_GB.
-
US
public static final Locale US
Locale constant for en_US.
-
PRIVATE_USE_EXTENSION
public static final char PRIVATE_USE_EXTENSION
BCP-47 extension identifier (or "singleton") for the private use extension. SeegetExtension(char)andLocale.Builder.setExtension(char, String).- Since:
- 1.7
- See Also:
- Constant Field Values
-
UNICODE_LOCALE_EXTENSION
public static final char UNICODE_LOCALE_EXTENSION
BCP-47 extension identifier (or "singleton") for the unicode locale extension. SeegetExtension(char)andLocale.Builder.setExtension(char, String).- Since:
- 1.7
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Locale
public Locale(String language)
Constructs a newLocaleusing the specified language.
-
Locale
public Locale(String language, String country)
Constructs a newLocaleusing the specified language and country codes.
-
Locale
public Locale(String language, String country, String variant, String scriptCode, Set<String> unicodeAttributes, Map<String,String> unicodeKeywords, Map<Character,String> extensions, boolean hasValidatedFields)
Required by libcore.icu.ICU.
-
-
Method Detail
-
getDefaultLocaleFromSystemProperties
public static Locale getDefaultLocaleFromSystemProperties()
Returns the default locale from system properties.
-
forLanguageTag
public static Locale forLanguageTag(String languageTag)
Returns a locale for a given BCP-47 language tag. This method is more lenient thanLocale.Builder.setLanguageTag(java.lang.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 exampleen-US.- Throws:
NullPointerException- iflanguageTagisnull.- Since:
- 1.7
-
clone
public Object clone()
Description copied from class:ObjectCreates and returns a copy of thisObject. 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 callsuper.clone()to create the new instance and then create deep copies of the nested, mutable objects.
-
equals
public boolean equals(Object object)
Returns true ifobjectis a locale with the same language, country and variant.- Overrides:
equalsin classObject- Parameters:
object- the object to compare this instance with.- Returns:
trueif the specified object is equal to thisObject;falseotherwise.- See Also:
Object.hashCode()
-
getAvailableLocales
public static Locale[] getAvailableLocales()
Returns the system's installed locales. This array always includesLocale.US, and usually several others. Most locale-sensitive classes offer their owngetAvailableLocalesmethod, which should be preferred over this general purpose method.
-
getCountry
public String getCountry()
Returns the country code for this locale, or""if this locale doesn't correspond to a specific country.
-
getDefault
public static Locale getDefault()
Returns the user's preferred locale. This may have been overridden for this process withsetDefault(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.
-
getDisplayCountry
public final String getDisplayCountry()
Equivalent togetDisplayCountry(Locale.getDefault()).
-
getDisplayCountry
public String getDisplayCountry(Locale locale)
Returns the name of this locale's country, localized tolocale. Returns the empty string if this locale does not correspond to a specific country.
-
getDisplayLanguage
public final String getDisplayLanguage()
Equivalent togetDisplayLanguage(Locale.getDefault()).
-
getDisplayLanguage
public String getDisplayLanguage(Locale locale)
Returns the name of this locale's language, localized tolocale. If the language name is unknown, the language code is returned.
-
getDisplayName
public final String getDisplayName()
Equivalent togetDisplayName(Locale.getDefault()).
-
getDisplayName
public String getDisplayName(Locale locale)
Returns this locale's language name, country name, and variant, localized tolocale. 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)->Englishnew 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)->anglaisnew Locale("en", "US").getDisplayName(Locale.FRANCE)->anglais (États-Unis)new Locale("en", "US", "POSIX").getDisplayName(Locale.FRANCE)->anglais (États-Unis,informatique).
-
getDisplayVariant
public final String getDisplayVariant()
Returns the full variant name in the defaultLocalefor the variant code of thisLocale. If there is no matching variant name, the variant code is returned.- Since:
- 1.7
-
getDisplayVariant
public String getDisplayVariant(Locale locale)
Returns the full variant name in the specifiedLocalefor the variant code of thisLocale. If there is no matching variant name, the variant code is returned.- Since:
- 1.7
-
getISO3Country
public String getISO3Country()
Returns the three-letter ISO 3166 country code which corresponds to the country code for thisLocale.- Throws:
MissingResourceException- if there's no 3-letter country code for this locale.
-
getISO3Language
public String getISO3Language()
Returns the three-letter ISO 639-2/T language code which corresponds to the language code for thisLocale.- Throws:
MissingResourceException- if there's no 3-letter language code for this locale.
-
getISOCountries
public 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 aLocale.
-
getISOLanguages
public 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 aLocale.
-
getLanguage
public String getLanguage()
Returns the language code for thisLocaleor the empty string if no language was set.
-
getVariant
public String getVariant()
Returns the variant code for thisLocaleor an emptyStringif no variant was set.
-
getScript
public String getScript()
Returns the script code for thisLocaleor an emptyStringif no script was set. If set, the script code will be a title cased string of length 4, as per the ISO 15924 specification.- Since:
- 1.7
-
getDisplayScript
public String getDisplayScript()
Equivalent togetDisplayScript(Locale.getDefault()))- Since:
- 1.7
-
getDisplayScript
public String getDisplayScript(Locale locale)
Returns the name of this locale's script code, localized toLocale. If the script code is unknown, the return value of this method is the same as that ofgetScript().- Since:
- 1.7
-
toLanguageTag
public 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 publicLocaleconstructors 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.- Since:
- 1.7
-
getExtensionKeys
public 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.- Since:
- 1.7
-
getExtension
public String getExtension(char extensionKey)
Returns the BCP-47 extension whose key isextensionKey, ornullif this locale does not contain the extension. Individual Keywords and attributes for the unicode locale extension can be fetched usinggetUnicodeLocaleAttributes(),getUnicodeLocaleKeys()andgetUnicodeLocaleType(java.lang.String).- Since:
- 1.7
-
getUnicodeLocaleType
public String getUnicodeLocaleType(String keyWord)
Returns thetypefor the specified unicode locale extensionkey. For more information about types and keywords, seeLocale.Builder.setUnicodeLocaleKeyword(java.lang.String, java.lang.String)and Unicode Technical Standard #35- Since:
- 1.7
-
getUnicodeLocaleAttributes
public Set<String> getUnicodeLocaleAttributes()
Returns the set of unicode locale extension attributes this locale contains. For more information about attributes, seeLocale.Builder.addUnicodeLocaleAttribute(java.lang.String)and Unicode Technical Standard #35- Since:
- 1.7
-
getUnicodeLocaleKeys
public Set<String> getUnicodeLocaleKeys()
Returns the set of unicode locale extension keywords this locale contains. For more information about types and keywords, seeLocale.Builder.setUnicodeLocaleKeyword(java.lang.String, java.lang.String)and Unicode Technical Standard #35- Since:
- 1.7
-
hashCode
public int hashCode()
Description copied from class:ObjectReturns an integer hash code for this object. By contract, any two objects for whichObject.equals(java.lang.Object)returnstruemust return the same hash code value. This means that subclasses ofObjectusually 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
hashCodemethod if you intend implementing your ownhashCodemethod.- Overrides:
hashCodein classObject- Returns:
- this object's hash code.
- See Also:
Object.equals(java.lang.Object)
-
setDefault
public static 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.
-
toString
public final String toString()
Returns the string representation of thisLocale. 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"
-
serializeExtensions
public static String serializeExtensions(Map<Character,String> extensionsMap)
The serialized form for extensions is straightforward. It's simply of the form key1-value1-key2-value2 where each value might in turn contain multiple subtags separated by hyphens. Each key is guaranteed to be a single character in length. This method assumes thatextensionsMapis non-empty. Visible for testing.
-
parseSerializedExtensions
public static void parseSerializedExtensions(String extString, Map<Character,String> outputMap)
Visible for testing.
-
parseUnicodeExtension
public static void parseUnicodeExtension(String[] subtags, Map<String,String> keywords, Set<String> attributes)
This extension is described by http://www.unicode.org/reports/tr35/#RFC5234 unicode_locale_extensions = sep "u" (1*(sep keyword) / 1*(sep attribute) *(sep keyword)). It must contain at least one keyword or attribute and attributes (if any) must appear before keywords. Attributes can't appear after keywords because they will be indistinguishable from a subtag of the keyword type. Visible for testing.
-
-