# Locale.Builder

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

# Builder

```
class Builder
```

|---|------------------------------------------------------------------------------------------------------|
| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html)                       ||
| ↳ | [java.util.Locale.Builder](https://developer.android.com/reference/kotlin/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.

## Summary

|                                                       Public constructors                                                        ||
|-------------------------------------------------------------------------------------------------------------------------------|---|
| [Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#Builder())`()` Constructs an empty Builder. |

|                                                                                                                                                                                                                                              Public methods                                                                                                                                                                                                                                              ||
|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [addUnicodeLocaleAttribute](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#addUnicodeLocaleAttribute(kotlin.String))`(`attribute:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)`)` Adds a unicode locale attribute, if not already present, otherwise has no effect.                                                                           |
| [Locale](https://developer.android.com/reference/kotlin/java/util/Locale)                  | [build](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#build())`()` Returns an instance of`Locale`obtained from the fields set on this builder.                                                                                                                                                                                                                                     |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [clear](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#clear())`()` Resets the builder to its initial, empty state.                                                                                                                                                                                                                                                                 |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [clearExtensions](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#clearExtensions())`()` Resets the extensions to their initial, empty state.                                                                                                                                                                                                                                        |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [removeUnicodeLocaleAttribute](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#removeUnicodeLocaleAttribute(kotlin.String))`(`attribute:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)`)` Removes a unicode locale attribute, if present, otherwise has no effect.                                                                              |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setExtension](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setExtension(kotlin.Char,%20kotlin.String))`(`key:` `[Char](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-char/index.html)`, `value:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?`)` Sets the extension for the given key.                                              |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setLanguage](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setLanguage(kotlin.String))`(`language:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?`)` Sets the language.                                                                                                                                                                      |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setLanguageTag](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setLanguageTag(kotlin.String))`(`languageTag:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)`)` Resets the Builder to match the provided IETF BCP 47 language tag.                                                                                                              |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setLocale](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setLocale(java.util.Locale))`(`locale:` `[Locale](https://developer.android.com/reference/kotlin/java/util/Locale)`)` Resets the`Builder`to match the provided`locale`.                                                                                                                                                  |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setRegion](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setRegion(kotlin.String))`(`region:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?`)` Sets the region.                                                                                                                                                                              |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setScript](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setScript(kotlin.String))`(`script:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?`)` Sets the script.                                                                                                                                                                              |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setUnicodeLocaleKeyword](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setUnicodeLocaleKeyword(kotlin.String,%20kotlin.String))`(`key:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)`, `type:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?`)` Sets the Unicode locale keyword type for the given key. |
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | [setVariant](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setVariant(kotlin.String))`(`variant:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?`)` Sets the variant.                                                                                                                                                                          |

## Public constructors

### Builder

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
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.html#ApiLevels)  

```
fun addUnicodeLocaleAttribute(attribute: String): Locale.Builder
```

Adds a unicode locale attribute, if not already present, otherwise has no effect. The attribute must not be null and must be java.util.Locale# or an exception is thrown.

|                                                 Parameters                                                  ||
|-------------|------------------------------------------------------------------------------------------------|
| `attribute` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html):the attribute |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                            Exceptions                            ||
|--------------------------------------|----------------------------|
| `java.lang.NullPointerException`     | if`attribute`is null       |
| `java.util.IllformedLocaleException` | if`attribute`is ill-formed |

**See Also**

- [#setExtension(char, String)](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setExtension(kotlin.Char,%20kotlin.String))  

### build

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun build(): Locale
```

Returns an instance of`Locale`obtained from the fields set on this builder.

This applies the conversions listed in[Locale.forLanguageTag](https://developer.android.com/reference/kotlin/java/util/Locale#forLanguageTag(kotlin.String))when constructing a Locale. (Legacy tags are handled in[setLanguageTag](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setLanguageTag(kotlin.String)).)

|                                        Return                                        ||
|---------------------------------------------------------------------------|-----------|
| [Locale](https://developer.android.com/reference/kotlin/java/util/Locale) | A Locale. |

### clear

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun clear(): Locale.Builder
```

Resets the builder to its initial, empty state.

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

### clearExtensions

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun clearExtensions(): Locale.Builder
```

Resets the extensions to their initial, empty state. Language, script, region and variant are unchanged.

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

**See Also**

- [#setExtension(char, String)](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setExtension(kotlin.Char,%20kotlin.String))  

### removeUnicodeLocaleAttribute

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun removeUnicodeLocaleAttribute(attribute: String): Locale.Builder
```

Removes a unicode locale attribute, if present, otherwise has no effect. The attribute must not be null and must be java.util.Locale# or an exception is thrown.

Attribute comparison for removal is case-insensitive.

|                                                 Parameters                                                  ||
|-------------|------------------------------------------------------------------------------------------------|
| `attribute` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html):the attribute |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                            Exceptions                            ||
|--------------------------------------|----------------------------|
| `java.lang.NullPointerException`     | if`attribute`is null       |
| `java.util.IllformedLocaleException` | if`attribute`is ill-formed |

**See Also**

- [#setExtension(char, String)](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setExtension(kotlin.Char,%20kotlin.String))  

### setExtension

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setExtension(
    key: Char, 
    value: String?
): Locale.Builder
```

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 java.util.Locale# or an exception is thrown.

**Note:** The key[UNICODE_LOCALE_EXTENSION](https://developer.android.com/reference/kotlin/java/util/Locale#UNICODE_LOCALE_EXTENSION:kotlin.Char)('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[PRIVATE_USE_EXTENSION](https://developer.android.com/reference/kotlin/java/util/Locale#PRIVATE_USE_EXTENSION:kotlin.Char)('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](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-char/index.html):the extension key        |
| `value` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?:the extension value |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                                   Exceptions                                   ||
|--------------------------------------|------------------------------------------|
| `java.util.IllformedLocaleException` | if`key`is illegal or`value`is ill-formed |

**See Also**

- [#setUnicodeLocaleKeyword(String, String)](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setUnicodeLocaleKeyword(kotlin.String,%20kotlin.String))  

### setLanguage

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setLanguage(language: String?): Locale.Builder
```

Sets the language. If`language`is the empty string or null, the language in this`Builder`is removed. Otherwise, the language must be java.util.Locale# or an exception is thrown.

The typical language value is a two or three-letter language code as defined in ISO639.

|                                                 Parameters                                                 ||
|------------|------------------------------------------------------------------------------------------------|
| `language` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?:the language |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                           Exceptions                            ||
|--------------------------------------|---------------------------|
| `java.util.IllformedLocaleException` | if`language`is ill-formed |

### setLanguageTag

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setLanguageTag(languageTag: String): Locale.Builder
```

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[clear](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#clear()). Legacy tags (see[java.util.Locale#forLanguageTag](https://developer.android.com/reference/kotlin/java/util/Locale#forLanguageTag(kotlin.String))) are converted to their canonical form before being processed. Otherwise, the language tag must be well-formed (see[Locale](https://developer.android.com/reference/kotlin/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](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html):the language tag |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                             Exceptions                             ||
|--------------------------------------|------------------------------|
| `java.util.IllformedLocaleException` | if`languageTag`is ill-formed |

**See Also**

- [java.util.Locale#forLanguageTag(String)](https://developer.android.com/reference/kotlin/java/util/Locale#forLanguageTag(kotlin.String))  

### setLocale

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setLocale(locale: Locale): Locale.Builder
```

Resets the`Builder`to match the provided`locale`. Existing state is discarded.

All fields of the locale must be well-formed, see[Locale](https://developer.android.com/reference/kotlin/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](https://developer.android.com/reference/kotlin/java/util/Locale):the locale |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                                 Exceptions                                 ||
|--------------------------------------|--------------------------------------|
| `java.util.IllformedLocaleException` | if`locale`has any ill-formed fields. |
| `java.lang.NullPointerException`     | if`locale`is null.                   |

### setRegion

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setRegion(region: String?): Locale.Builder
```

Sets the region. If region is null or the empty string, the region in this`Builder`is removed. Otherwise, the region must be java.util.Locale# 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](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?:the region |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                          Exceptions                           ||
|--------------------------------------|-------------------------|
| `java.util.IllformedLocaleException` | if`region`is ill-formed |

### setScript

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setScript(script: String?): Locale.Builder
```

Sets the script. If`script`is null or the empty string, the script in this`Builder`is removed. Otherwise, the script must be java.util.Locale# or an exception is thrown.

The typical script value is a four-letter script code as defined by ISO 15924.

|                                               Parameters                                               ||
|----------|----------------------------------------------------------------------------------------------|
| `script` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?:the script |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                          Exceptions                           ||
|--------------------------------------|-------------------------|
| `java.util.IllformedLocaleException` | if`script`is ill-formed |

### setUnicodeLocaleKeyword

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setUnicodeLocaleKeyword(
    key: String, 
    type: String?
): Locale.Builder
```

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 java.util.Locale# or an exception is thrown.

Keys and types are converted to lower case.

**Note** :Setting the 'u' extension via[setExtension](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setExtension(kotlin.Char,%20kotlin.String))replaces all Unicode locale keywords with those defined in the extension.

|                                                    Parameters                                                     ||
|--------|-----------------------------------------------------------------------------------------------------------|
| `key`  | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html):the Unicode locale key   |
| `type` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?:the Unicode locale type |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                             Exceptions                             ||
|--------------------------------------|------------------------------|
| `java.util.IllformedLocaleException` | if`key`or`type`is ill-formed |
| `java.lang.NullPointerException`     | if`key`is null               |

**See Also**

- [#setExtension(char, String)](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#setExtension(kotlin.Char,%20kotlin.String))  

### setVariant

Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)  

```
fun setVariant(variant: String?): Locale.Builder
```

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 java.util.Locale# 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[Locale.of(String, String, String)](https://developer.android.com/reference/kotlin/java/util/Locale#of(kotlin.String,%20kotlin.String,%20kotlin.String)).

|                                                Parameters                                                ||
|-----------|-----------------------------------------------------------------------------------------------|
| `variant` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)?:the variant |

|                                                  Return                                                   ||
|--------------------------------------------------------------------------------------------|---------------|
| [Locale.Builder](https://developer.android.com/reference/kotlin/java/util/Locale.Builder#) | This builder. |

|                           Exceptions                           ||
|--------------------------------------|--------------------------|
| `java.util.IllformedLocaleException` | if`variant`is ill-formed |

**See Also**

- [java.util.Locale#of(String, String, String)](https://developer.android.com/reference/kotlin/java/util/Locale#of(kotlin.String,%20kotlin.String,%20kotlin.String))