Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Text, Formatting and Regex

The Locale class

Reference for java.util.Locale: Locale.of(), forLanguageTag(), predefined constants, display names, the default locale and the Turkish toUpperCase trap.

A java.util.Locale identifies a language, optionally with a country or region, a script and variants. It does not format anything by itself. It is a key that locale-sensitive classes (NumberFormat, DateTimeFormatter, String.format, ResourceBundle, String.toUpperCase) use to pick conventions: decimal separators, month names, plural rules, case mapping.

You create locales with Locale.of(language, country) (Java 19), parse them from a BCP 47 language tag with Locale.forLanguageTag("pt-BR"), or use a predefined constant such as Locale.US or Locale.GERMANY. The new Locale(...) constructors are deprecated since Java 19.

Java
Locale brazil = Locale.of("pt", "BR");
Locale same = Locale.forLanguageTag("pt-BR");

Try it

Java Creating and describing locales

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Why the locale changes your output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public static Locale of(String language)
public static Locale of(String language, String country)
public static Locale of(String language, String country, String variant)
public static Locale forLanguageTag(String languageTag)
public static Locale getDefault()
public static void setDefault(Locale newLocale)
Member Description
Locale.of(...) creates a locale; language is normalized to lower case, country to upper case (Java 19)
forLanguageTag(String) parses a BCP 47 tag like en-US or zh-Hant-TW; ill-formed parts are dropped
new Locale.Builder() builds locales with script, extensions and validation (IllformedLocaleException)
getLanguage(), getCountry(), getScript(), getVariant() the components, as strings (empty when absent)
toLanguageTag() BCP 47 form, pt-BR; toString() gives pt_BR
getDisplayName(Locale), getDisplayLanguage(Locale), getDisplayCountry(Locale) human-readable names in the language of the argument
getDefault(), getDefault(Locale.Category) the JVM default (FORMAT or DISPLAY category)
Locale.ROOT, ENGLISH, US, UK, GERMANY, FRANCE, JAPAN, ... predefined constants
getAvailableLocales() locales with installed data (depends on the JDK)

Usage notes

  • Use Locale.ROOT for machine text. Calling toUpperCase(), toLowerCase() or String.format() without a locale uses the default one. In a Turkish or Azerbaijani default, "title".toUpperCase() gives a dotted capital I and breaks keyword comparisons. Use toUpperCase(Locale.ROOT) for identifiers, protocol keywords and file extensions.
  • The default is global, mutable state. Locale.setDefault() affects the whole JVM, including other threads. Prefer passing a locale explicitly; never change the default in library code or in the middle of a request.
  • Constructors are deprecated. new Locale("en", "US") still works, but use Locale.of() or forLanguageTag(). Since Java 19 of() can return cached instances.
  • No validation by of(). Locale.of("xx", "YY") is accepted and simply has no data; formatting falls back to a parent locale, then to root.
  • Language, country, region. en is a language, en-US and en-GB are regional variants. A locale is a set of preferences, not a promise that translated text exists.
  • Locale data comes from CLDR (the default since Java 9), so output for the same locale can differ slightly between JDK versions.
  • Locale.Category lets applications use one locale for formatting numbers and another for display text. Most code just uses the default for both.