Java Locale Class: What a Locale Is and How to Create One

The string "en_US" looks like a valid locale code, but Locale.forLanguageTag("en_US") returns an empty locale: its toString() is "" and getDisplayLanguage() is an empty string too. No exception is thrown. ResourceBundle quietly loads the base resource file without a suffix, and nobody notices that the English texts never showed up. This lesson explains why that happens and how to create a Locale correctly.

A locale is a set of regional settings: a language, a country (region) and, when needed, a script and a variant. In Java a locale is represented by the java.util.Locale class. It lets your code respect regional conventions for alphabets, symbols, numbers and dates. When the JVM starts, it takes the default locale from the operating system settings, but you can change it or pass a specific locale to a particular method.

A Locale does not format anything by itself. It is a label for a language and region that you pass to NumberFormat, DateTimeFormatter, ResourceBundle and other classes. Why an application needs this at all is covered in the lesson on internationalization and localization in Java.

How to create a Locale: 5 ways

In modern Java you create a locale with the factory method Locale.of("de", "DE") (Java 19+) or from a BCP 47 language tag with Locale.forLanguageTag("de-DE"). For a handful of countries there are ready-made constants such as Locale.US. The new Locale(...) constructor still compiles, but it has been deprecated since Java 19.

All three modern ways produce the same locale:

import java.util.Locale;

public class CreateLocale {
    public static void main(String[] args) {
        Locale a = Locale.of("de", "DE");
        Locale b = Locale.forLanguageTag("de-DE");
        Locale c = new Locale.Builder().setLanguage("de").setRegion("DE").build();

        System.out.println(a + " " + b + " " + c);
        System.out.println(a.equals(b) && b.equals(c));
    }
}
// Output:
// de_DE de_DE de_DE
// true

The language code is written in lowercase (ISO 639: en, de, fr), the country code in uppercase (ISO 3166: US, DE, FR). If your project runs on Java 8–18, where Locale.of does not exist yet, use Locale.forLanguageTag: it has been available since Java 7 and is not deprecated in newer versions.

Locale.US, Locale.FRANCE and other constants

The Locale class has ready-made constants for a few countries (language + country) and languages (language only). There are no constants for most countries, for example Brazil or Spain. Create those locales with Locale.of("pt", "BR") or Locale.forLanguageTag("pt-BR").

The difference between Locale.US and Locale.ENGLISH shows up, for example, when formatting currency: en_US has a country and therefore a currency (the dollar), while en has no country.

Locale.ROOT: a locale with no language or country

Locale.ROOT is the constant for the neutral locale whose language and country are both the empty string "". It is the base of all other locales and is used wherever a result must not depend on language or region: keys, identifiers, file and protocol formats.

System.out.println("[" + Locale.ROOT + "]");          // Output: []
System.out.println(Locale.ROOT.toLanguageTag());      // Output: und
System.out.println("[" + Locale.ROOT.getDisplayName() + "]"); // Output: []
System.out.println(Locale.ROOT.equals(Locale.of(""))); // Output: true

und is the BCP 47 tag for an "undetermined" language. Locale.ROOT is used for:

• Locale-independent operations: toUpperCase(Locale.ROOT), String.format(Locale.ROOT, ...). Without an explicit locale these methods use the default locale, so the result on a server can differ from the result on the developer's machine. Examples of such bugs, including the Turkish letter i, are in the lesson on internationalization.
• Base resources: a text.properties file without a suffix corresponds to Locale.ROOT. It is the last stop in the ResourceBundle lookup: the bundle uses it when neither the requested locale nor the default locale has its own file.

The default locale: getDefault and setDefault

Locale.getDefault() returns the current locale of the JVM. You can change it with Locale.setDefault(Locale) or with the startup options -Duser.language and -Duser.country. The default locale is determined once, when the JVM starts, from the operating system settings.

Locale current = Locale.getDefault();   // for example, en_US on an English-language Windows
Locale.setDefault(Locale.CANADA);       // now en_CA for the whole JVM

You can also set the locale at startup, without changing the code:

java -Duser.language=de -Duser.country=DE Main

Since Java 7 the default locale has two categories (Locale.Category). DISPLAY controls the language of names (getDisplayCountry() and so on), and FORMAT controls the format of numbers, dates and currencies. setDefault(Locale) changes both categories at once, while setDefault(Category, Locale) changes only one and does not touch the general getDefault():

import java.util.Locale;

public class DefaultLocaleCategories {
    public static void main(String[] args) {
        Locale start = Locale.getDefault();
        Locale.setDefault(Locale.Category.FORMAT, Locale.GERMANY);
        Locale.setDefault(Locale.Category.DISPLAY, Locale.ENGLISH);

        System.out.println(Locale.getDefault().equals(start)); // the general locale did not change
        System.out.println(String.format("%,.2f", 1234.5));    // the format comes from FORMAT
        System.out.println(Locale.FRANCE.getDisplayCountry()); // the name comes from DISPLAY
    }
}
// Output:
// true
// 1.234,50
// France

Calling Locale.setDefault(null) throws a NullPointerException.

Locale methods and an example

The methods of Locale fall into two groups. Codes (getLanguage(), getCountry()) return what is stored in the object. Names (getDisplayLanguage(), getDisplayCountry()) are translated into the language of the default DISPLAY locale, or into the language of the locale you pass as an argument.

Here is a Java Locale example. The default locale is replaced with Locale.CANADA, so all names are printed in English:

import java.util.Locale;

public class LocaleExample1 {
    public static void main(String[] args) {
        Locale fr = Locale.FRANCE;
        Locale us = Locale.US;
        Locale br = Locale.of("pt", "BR");

        Locale.setDefault(Locale.CANADA);
        Locale current = Locale.getDefault();
        getLocaleInfo(current);

        getLocaleInfo(fr);
        getLocaleInfo(us);
        getLocaleInfo(br);
    }

    private static void getLocaleInfo(Locale locale) {
        System.out.println("Country code: " + locale.getCountry());
        System.out.println("Country name: " + locale.getDisplayCountry());
        System.out.println("Language code: " + locale.getLanguage());
        System.out.println("Language name: "
                + locale.getDisplayLanguage());
        System.out.println();
    }
}

Output (Java 11+):

Country code: CA
Country name: Canada
Language code: en
Language name: English

Country code: FR
Country name: France
Language code: fr
Language name: French

Country code: US
Country name: United States
Language code: en
Language name: English

Country code: BR
Country name: Brazil
Language code: pt
Language name: Portuguese

To get names in German regardless of the default locale, pass the locale as an argument:

Locale de = Locale.of("de", "DE");

System.out.println(de.getDisplayName(de));                // Output: Deutsch (Deutschland)
System.out.println(Locale.FRANCE.getDisplayCountry(de));  // Output: Frankreich
System.out.println(Locale.FRANCE.getDisplayLanguage(de)); // Output: Französisch
System.out.println(de.toLanguageTag());                   // Output: de-DE
System.out.println(de.getISO3Country());                  // Output: DEU

Locale mistakes that fail silently

Most Locale mistakes do not throw an exception: a wrong locale is created silently, and the problem shows up later, when a text or a format turns out to be wrong. The main rule: toString() gives en_US with an underscore, but forLanguageTag expects en-US with a hyphen.

Mistake 1: an underscore in forLanguageTag. This is the example from the start of the lesson.

Locale bad = Locale.forLanguageTag("en_US");
System.out.println("[" + bad + "]");                   // Output: []
System.out.println(bad.equals(Locale.ROOT));           // Output: true

// Fix: replace the underscore with a hyphen
Locale good = Locale.forLanguageTag("en_US".replace('_', '-'));
System.out.println(good);                              // Output: en_US

Mistake 2: Locale.of does not validate its arguments. The whole string becomes the language code:

Locale wrong = Locale.of("de_DE");
System.out.println(wrong.getLanguage());     // Output: de_de
System.out.println("[" + wrong.getCountry() + "]"); // Output: []

If a locale code comes from outside (settings, a database, an HTTP request), use Locale.Builder: it validates the values and throws IllformedLocaleException, for example on new Locale.Builder().setLanguage("de_DE").

Mistake 3: setDefault as a way to "translate" one screen. Calling Locale.setDefault inside a request handler changes the locale for every thread in the JVM. Pass the locale explicitly: NumberFormat.getInstance(locale), ResourceBundle.getBundle("text", locale).