setLocale()

Sets the locale with the given time locale value.

Syntax

Calendar setLocale(String locale)
  1. locale logically consists of the fields in Table 1.
Table 1. Locale fields
Field name Description
language

ISO 639 alpha-2 or alpha-3 language code, or registered language subtags up to 8 alpha letters (for future enhancements). When a language has both an alpha-2 code and an alpha-3 code, the alpha-2 code must be used. You can find a full list of valid language codes in the IANA Language Subtag Registry (search for "Type: language"). The language field is case insensitive, but Locale always canonicalizes to lower case.

Well-formed language values have the form:
[a-zA-Z]{2,8}
Note:

This is not the the full BCP47 language production, because it excludes extlang. They are not needed since modern three-letter language codes replace them.

For example: "en" (English), "ja" (Japanese), "kok" (Konkani)

script

ISO 15924 alpha-4 script code. You can find a full list of valid script codes in the IANA Language Subtag Registry (search for "Type: script"). The script field is case insensitive, but Locale always canonicalizes to title case (the first letter is upper case and the rest of the letters are lower case).

Well-formed script values have the form:
[a-zA-Z]{4}

For example: "Latn" (Latin), "Cyrl" (Cyrillic)

country (region)

ISO 3166 alpha-2 country code or UN M.49 numeric-3 area code. You can find a full list of valid country and region codes in the IANA Language Subtag Registry (search for "Type: region"). The country (region) field is case insensitive, but Locale always canonicalizes to upper case.

Well-formed country/region values have the form:
[a-zA-Z]{2} | [0-9]{3}

For example: "US" (United States), "FR" (France), "029" (Caribbean)

variant

Any arbitrary value used to indicate a variation of a Locale. Where there are two or more variant values each indicating its own semantics, these values should be ordered by importance, with most important first, separated by underscore('_'). The variant field is case sensitive.

Well-formed variant values have the form:
SUBTAG (('_'|'-') SUBTAG)*
where SUBTAG = [0-9][0-9a-zA-Z]{3} | [0-9a-zA-Z]{5,8}
Note:

BCP 47 only uses hyphen ('-') as a delimiter, this is more lenient.

For example: "polyton" (Polytonic Greek), "POSIX"

extensions

A map from single character keys to string values, indicating extensions apart from language identification. The extensions in Locale implement the semantics and syntax of BCP 47 extension subtags and private use subtags. The extensions are case insensitive, but Locale canonicalizes all extension keys and values to lower case.

Note:

Extensions cannot have empty values.

Well-formed keys are single characters from the set [0-9a-zA-Z].

Well-formed values have the form:
SUBTAG ('-' SUBTAG)*
where for the key 'x', SUBTAG = [0-9a-zA-Z]{1,8} and for other keys SUBTAG = [0-9a-zA-Z]{2,8} (that is, 'x' allows single-character subtags).

For example: key="u"/value="ca-japanese" (Japanese Calendar), key="x"/value="java-1-7"

Unicode locale/language extension

UTS#35, "Unicode Locale Data Markup Language" defines optional attributes and keywords to override or refine the default behavior associated with a locale. A keyword is represented by a pair of key and type. For example, "nu-thai" indicates that Thai local digits (value:"thai") should be used for formatting numbers (key:"nu").

The keywords are mapped to a BCP 47 extension value using the extension key 'u'. The above example, "nu-thai", becomes the extension "u-nu-thai".code

A well-formed locale key has the form:
[0-9a-zA-Z]{2}
A well-formed locale type has the form:
"" | [0-9a-zA-Z]{3,8} ('-'[0-9a-zA-Z]{3,8})*
It can be empty, or a series of subtags 3-8 alphanums in length.
A well-formed locale attribute has the form:
[0-9a-zA-Z]{3,8}
It is a single subtag with the same form as a locale type subtag.

Usage

For example, set the locale value to English by calling:
Calendar.fromDate(Date.parseString("05/08/1999","mm/dd/yyyy")).setLocale("English").toDate().format("mm/dd/yyyy")
This example populates a Word Box. To achieve the same goal and populate a Date box, call:
Calendar.fromDate(Date.parseString("05/08/1999","mm/dd/yyyy")).setLocale("English").toDate()