Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Ctors](https://developer.android.com/reference/java/util/Locale.Builder#pubctors) \| [Methods](https://developer.android.com/reference/java/util/Locale.Builder#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/java/util/Locale.Builder#inhmethods)
# Locale.Builder
` public static final class Locale.Builder `
` extends https://developer.android.com/reference/java/lang/Object ` ` `
|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | java.util.Locale.Builder |
*** ** * ** ***
`Builder` is used to build instances of `Locale` from values configured by the setters. Unlike the `Locale` constructors or `Locale.of()` factory methods, the `Builder` checks if a value configured by a setter satisfies the syntax requirements defined by the `Locale` class. A `Locale` object obtained from a `Builder` is well-formed and can be transformed to a well-formed IETF BCP 47 language tag without losing information.
**See also:**
- `https://developer.android.com/reference/java/util/Locale#forLanguageTag(java.lang.String)`
- `https://developer.android.com/reference/java/util/Locale#of(java.lang.String,%20java.lang.String,%20java.lang.String)`
## Summary
| ### Public constructors ||
|---|---|
| ` https://developer.android.com/reference/java/util/Locale.Builder#Builder()() ` Constructs an empty Builder. |
| ### Public methods ||
|---|---|
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#addUnicodeLocaleAttribute(java.lang.String)(https://developer.android.com/reference/java/lang/String attribute) ` Adds a unicode locale attribute, if not already present, otherwise has no effect. |
| ` https://developer.android.com/reference/java/util/Locale` | ` https://developer.android.com/reference/java/util/Locale.Builder#build()() ` Returns an instance of `Locale` obtained from the fields set on this builder. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#clear()() ` Resets the builder to its initial, empty state. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#clearExtensions()() ` Resets the extensions to their initial, empty state. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#removeUnicodeLocaleAttribute(java.lang.String)(https://developer.android.com/reference/java/lang/String attribute) ` Removes a unicode locale attribute, if present, otherwise has no effect. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setExtension(char,%20java.lang.String)(char key, https://developer.android.com/reference/java/lang/String value) ` Sets the extension for the given key. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setLanguage(java.lang.String)(https://developer.android.com/reference/java/lang/String language) ` Sets the language. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setLanguageTag(java.lang.String)(https://developer.android.com/reference/java/lang/String languageTag) ` Resets the Builder to match the provided IETF BCP 47 language tag. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setLocale(java.util.Locale)(https://developer.android.com/reference/java/util/Locale locale) ` Resets the `Builder` to match the provided `locale`. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setRegion(java.lang.String)(https://developer.android.com/reference/java/lang/String region) ` Sets the region. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setScript(java.lang.String)(https://developer.android.com/reference/java/lang/String script) ` Sets the script. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setUnicodeLocaleKeyword(java.lang.String,%20java.lang.String)(https://developer.android.com/reference/java/lang/String key, https://developer.android.com/reference/java/lang/String type) ` Sets the Unicode locale keyword type for the given key. |
| ` https://developer.android.com/reference/java/util/Locale.Builder` | ` https://developer.android.com/reference/java/util/Locale.Builder#setVariant(java.lang.String)(https://developer.android.com/reference/java/lang/String variant) ` Sets the variant. |
### Inherited methods
From class ` https://developer.android.com/reference/java/lang/Object ` ` https://developer.android.com/reference/java/lang/Object` ` https://developer.android.com/reference/java/lang/Object#clone()() `
Creates and returns a copy of this object.
` boolean` ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) `
Indicates whether some other object is "equal to" this one.
` void` ` https://developer.android.com/reference/java/lang/Object#finalize()() `
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
` final https://developer.android.com/reference/java/lang/Class` ` https://developer.android.com/reference/java/lang/Object#getClass()() `
Returns the runtime class of this `Object`.
` int` ` https://developer.android.com/reference/java/lang/Object#hashCode()() `
Returns a hash code value for the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#notify()() `
Wakes up a single thread that is waiting on this object's monitor.
` final void` ` https://developer.android.com/reference/java/lang/Object#notifyAll()() `
Wakes up all threads that are waiting on this object's monitor.
` https://developer.android.com/reference/java/lang/String` ` https://developer.android.com/reference/java/lang/Object#toString()() `
Returns a string representation of the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait()() `
Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*.
## Public constructors
### Builder
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Builder ()
```
Constructs an empty Builder. The default value of all fields, extensions, and private use information is the empty string.
## Public methods
### addUnicodeLocaleAttribute
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder addUnicodeLocaleAttribute (String attribute)
```
Adds a unicode locale attribute, if not already present, otherwise has no effect. The attribute must not be null and must be [ERROR(well-formed/java.util.Locale##def_locale_extension well-formed)](https://developer.android.com/) or an exception is thrown.
| Parameters ||
|---|---|
| `attribute` | `String`: the attribute
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `attribute` is null |
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `attribute` is ill-formed |
**See also:**
- `https://developer.android.com/reference/java/util/Locale.Builder#setExtension(char,%20java.lang.String)`
### build
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale build ()
```
Returns an instance of `Locale` obtained from the fields set on this builder.
This applies the conversions listed in `https://developer.android.com/reference/java/util/Locale#forLanguageTag(java.lang.String)` when constructing a Locale. (Legacy tags are handled in `https://developer.android.com/reference/java/util/Locale.Builder#setLanguageTag(java.lang.String)`.)
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale` | A Locale.
|
### clear
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder clear ()
```
Resets the builder to its initial, empty state.
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
### clearExtensions
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder clearExtensions ()
```
Resets the extensions to their initial, empty state. Language, script, region and variant are unchanged.
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
**See also:**
- `https://developer.android.com/reference/java/util/Locale.Builder#setExtension(char,%20java.lang.String)`
### removeUnicodeLocaleAttribute
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder removeUnicodeLocaleAttribute (String attribute)
```
Removes a unicode locale attribute, if present, otherwise has no effect. The attribute must not be null and must be [ERROR(well-formed/java.util.Locale##def_locale_extension well-formed)](https://developer.android.com/) or an exception is thrown.
Attribute comparison for removal is case-insensitive.
| Parameters ||
|---|---|
| `attribute` | `String`: the attribute
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `attribute` is null |
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `attribute` is ill-formed |
**See also:**
- `https://developer.android.com/reference/java/util/Locale.Builder#setExtension(char,%20java.lang.String)`
### setExtension
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setExtension (char key,
String value)
```
Sets the extension for the given key. If the value is null or the empty string, the extension is removed. Otherwise, the extension must be [ERROR(well-formed/java.util.Locale##def_extensions well-formed)](https://developer.android.com/) or an exception is thrown.
**Note:** The key `https://developer.android.com/reference/java/util/Locale#UNICODE_LOCALE_EXTENSION` ('u') is used for the Unicode locale extension. Setting a value for this key replaces any existing Unicode locale key/type pairs with those defined in the extension.
**Note:** The key `https://developer.android.com/reference/java/util/Locale#PRIVATE_USE_EXTENSION` ('x') is used for the private use code. To be well-formed, the value for this key needs only to have subtags of one to eight alphanumeric characters, not two to eight as in the general case.
| Parameters ||
|---|---|
| `key` | `char`: the extension key
|
| `value` | `String`: the extension value
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `key` is illegal or `value` is ill-formed |
**See also:**
- `https://developer.android.com/reference/java/util/Locale.Builder#setUnicodeLocaleKeyword(java.lang.String,%20java.lang.String)`
### setLanguage
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setLanguage (String language)
```
Sets the language. If `language` is the empty string or null, the language in this `Builder` is removed. Otherwise, the language must be [ERROR(well-formed/java.util.Locale##def_language well-formed)](https://developer.android.com/) or an exception is thrown.
The typical language value is a two or three-letter language code as defined in ISO639.
| Parameters ||
|---|---|
| `language` | `String`: the language
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `language` is ill-formed |
### setLanguageTag
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setLanguageTag (String languageTag)
```
Resets the Builder to match the provided IETF BCP 47 language tag. Discards the existing state. Null and the empty string cause the builder to be reset, like `https://developer.android.com/reference/java/util/Locale.Builder#clear()`. Legacy tags (see `https://developer.android.com/reference/java/util/Locale#forLanguageTag(java.lang.String)`) are converted to their canonical form before being processed. Otherwise, the language tag must be well-formed (see `https://developer.android.com/reference/java/util/Locale`) or an exception is thrown (unlike `Locale.forLanguageTag`, which just discards ill-formed and following portions of the tag).
| Parameters ||
|---|---|
| `languageTag` | `String`: the language tag
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `languageTag` is ill-formed |
**See also:**
- `https://developer.android.com/reference/java/util/Locale#forLanguageTag(java.lang.String)`
### setLocale
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setLocale (Locale locale)
```
Resets the `Builder` to match the provided `locale`. Existing state is discarded.
All fields of the locale must be well-formed, see `https://developer.android.com/reference/java/util/Locale`.
Locales with any ill-formed fields cause `IllformedLocaleException` to be thrown, except for the following three cases which are accepted for compatibility reasons:
- Locale("ja", "JP", "JP") is treated as "ja-JP-u-ca-japanese"
- Locale("th", "TH", "TH") is treated as "th-TH-u-nu-thai"
- Locale("no", "NO", "NY") is treated as "nn-NO"
| Parameters ||
|---|---|
| `locale` | `Locale`: the locale
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `locale` is null. |
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `locale` has any ill-formed fields. |
### setRegion
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setRegion (String region)
```
Sets the region. If region is null or the empty string, the region in this `Builder` is removed. Otherwise, the region must be [ERROR(well-formed/java.util.Locale##def_region well-formed)](https://developer.android.com/) or an exception is thrown.
The typical region value is a two-letter ISO 3166 code or a three-digit UN M.49 area code.
The country value in the `Locale` obtained from a `Builder` is always normalized to upper case.
| Parameters ||
|---|---|
| `region` | `String`: the region
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `region` is ill-formed |
### setScript
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setScript (String script)
```
Sets the script. If `script` is null or the empty string, the script in this `Builder` is removed. Otherwise, the script must be [ERROR(well-formed/java.util.Locale##def_script well-formed)](https://developer.android.com/) or an exception is thrown.
The typical script value is a four-letter script code as defined by ISO 15924.
| Parameters ||
|---|---|
| `script` | `String`: the script
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `script` is ill-formed |
### setUnicodeLocaleKeyword
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setUnicodeLocaleKeyword (String key,
String type)
```
Sets the Unicode locale keyword type for the given key. If the type is null, the Unicode keyword is removed. Otherwise, the key must be non-null and both key and type must be [ERROR(well-formed/java.util.Locale##def_locale_extension well-formed)](https://developer.android.com/) or an exception is thrown.
Keys and types are converted to lower case.
**Note** :Setting the 'u' extension via `https://developer.android.com/reference/java/util/Locale.Builder#setExtension(char,%20java.lang.String)` replaces all Unicode locale keywords with those defined in the extension.
| Parameters ||
|---|---|
| `key` | `String`: the Unicode locale key
|
| `type` | `String`: the Unicode locale type
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if `key` is null |
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `key` or `type` is ill-formed |
**See also:**
- `https://developer.android.com/reference/java/util/Locale.Builder#setExtension(char,%20java.lang.String)`
### setVariant
Added in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public Locale.Builder setVariant (String variant)
```
Sets the variant. If variant is null or the empty string, the variant in this `Builder` is removed. Otherwise, it must consist of one or more [ERROR(well-formed/java.util.Locale##def_variant well-formed)](https://developer.android.com/) subtags, or an exception is thrown.
**Note:** This method checks if `variant` satisfies the IETF BCP 47 variant subtag's syntax requirements, and normalizes the value to lowercase letters. However, the `Locale` class does not impose any syntactic restriction on variant, and the variant value in `Locale` is case sensitive. To set such a variant, use `https://developer.android.com/reference/java/util/Locale#of(java.lang.String,%20java.lang.String,%20java.lang.String)`.
| Parameters ||
|---|---|
| `variant` | `String`: the variant
|
| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Locale.Builder` | This builder.
|
| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/IllformedLocaleException` | if `variant` is ill-formed |
**See also:**
- `https://developer.android.com/reference/java/util/Locale#of(java.lang.String,%20java.lang.String,%20java.lang.String)`