Java Localization: Locales, Resource Bundles and Formatting Numbers, Dates and Messages (1Z0-831)

A java.util.Locale names a language, optionally with a region (country), script and variant, and you get one in four ways: the factory Locale.of(language, country) (Java 19+; the old constructors are deprecated), a constant such as Locale.US, Locale.UK, Locale.GERMANY, Locale.FRANCE, Locale.JAPAN, Locale.CANADA_FRENCH or the language-only Locale.FRENCH and Locale.ENGLISH, parsing a BCP 47 tag with Locale.forLanguageTag("de-CH"), or the validating Locale.Builder. Locale.ROOT is the empty locale: no language, no region.

The four routes differ in how forgiving they are, and that difference is where code goes wrong:

A locale has two text forms. toString() joins the parts with underscores (ja_JP) and is the suffix used in resource-bundle file names; toLanguageTag() produces the BCP 47 tag with hyphens (ja-JP), the form forLanguageTag reads back. Locale.ROOT.toString() is the empty string, so printing it prints nothing, and its language tag is und. Two locales are equals only when every field matches, so a root locale never equals the locale the tag was meant to name.

import java.util.Locale;

public class Main {
    public static void main(String[] args) {
        Locale a = Locale.of("ja", "JP");
        Locale b = Locale.forLanguageTag("de_CH");
        System.out.println(a + " " + a.toLanguageTag());
        System.out.println("[" + b + "] " + Locale.of("DE", "ch"));
    }
}

This prints ja_JP ja-JP and then [] de_CH: the underscore tag silently became the root locale, while Locale.of lower-cased the language and upper-cased the country.

The JVM keeps one general default locale plus two category defaults, and every locale-sensitive API that is not given a Locale reads one of them. Locale.Category.FORMAT is used to format and parse numbers, dates, currencies and messages; Locale.Category.DISPLAY is used for the human-readable names of locales themselves; and the general default (Locale.getDefault() with no argument) is what ResourceBundle.getBundle falls back to.

Order therefore matters: a category call followed by the one-argument setDefault is undone, while the one-argument call followed by a category call leaves a mixed setup.

import java.text.NumberFormat;
import java.util.Locale;

public class Main {
    public static void main(String[] args) {
        Locale nl = Locale.of("nl", "NL");
        Locale.setDefault(Locale.UK);
        Locale.setDefault(Locale.Category.FORMAT, nl);
        System.out.println(NumberFormat.getInstance().format(9876.25));
        System.out.println(nl.getDisplayCountry());
        System.out.println(Locale.getDefault());
        Locale.setDefault(Locale.UK);
        System.out.println(Locale.getDefault(Locale.Category.FORMAT));
    }
}

The output is 9.876,25 (FORMAT is Dutch, which groups with a point and uses a decimal comma), Netherlands (DISPLAY is still English, so the country name is in English), en_GB (the general default ignores category calls), and finally en_GB again, because the last one-argument setDefault reset FORMAT too.

The safest habit in real code is to pass a Locale explicitly; an explicit argument always beats any default.

ResourceBundle.getBundle(baseName, locale) returns the first bundle that exists in a fixed candidate search: the requested locale from most to least specific, then the default locale the same way, and finally the base bundle. A resource bundle is a set of key–value pairs for one locale, found by name: base name Menu plus a locale suffix gives Menu_es_MX, Menu_es and the base bundle Menu.

For getBundle("Menu", Locale.of("es", "MX")) with default de_DE the search is:

1. Menu_es_MX, then Menu_es (the requested locale)
2. Only if neither exists: Menu_de_DE, then Menu_de (the general default locale)
3. Only if those fail as well: the base bundle Menu
4. Nothing at all: MissingResourceException

Three details decide most outcomes:

• A partial match wins over the default. Requesting es_AR or es_CL when only Menu_es exists returns Menu_es; the default locale is never consulted.
• The fallback reads the general default, not FORMAT or DISPLAY. If the default has no files either (say a Korean default with no Korean bundle), the search ends at the base bundle.
• A Locale.ROOT request accepts the base bundle without trying the default locale. Its own candidate list is just the base bundle, so when the base bundle exists it is returned straight away. The default locale is tried only when there is no base bundle: with only Only_de.properties on the class path and a German default, getBundle("Only", Locale.ROOT) returns the de bundle rather than throwing.

getLocale() on the result tells you which bundle was actually loaded: es for Menu_es, de for Menu_de, and Locale.ROOT (printed as an empty string) for the base bundle. It is not the locale you asked for.

Given Menu.properties (title=Welcome, exit=Quit), Menu_de.properties (title=Willkommen, exit=Beenden), Menu_es.properties (title=Bienvenido) and Menu_es_MX.properties (title=Hola):

import java.util.*;

public class Main {
    public static void main(String[] args) {
        Locale.setDefault(Locale.GERMANY);
        show(Locale.of("es", "MX"));
        show(Locale.of("es", "AR"));
        show(Locale.JAPAN);
        show(Locale.ROOT);
    }

    static void show(Locale loc) {
        var rb = ResourceBundle.getBundle("Menu", loc);
        System.out.println("[" + rb.getLocale() + "] "
            + rb.getString("title") + " " + rb.getString("exit"));
    }
}

The program prints [es_MX] Hola Quit, [es] Bienvenido Quit, [de] Willkommen Beenden and [] Welcome Quit. Argentina has no file of its own, so the partial match Menu_es wins; Japanese has no files at all, so the search falls to the default de_DE and lands on Menu_de; ROOT takes the base bundle that exists. The Quit in the first two lines comes from the parent chain, explained next.

Once a bundle is chosen, a key that it does not define is looked up in its parents: the same base name with the locale shortened one level at a time, ending at the base bundle. Menu_es_MX has parent Menu_es, whose parent is Menu. That is why exit above resolved to Quit from the base file even though Menu_de, the default locale's file, defines it.

• The default locale is never a parent. Its files only matter when they are chosen as the result bundle in the fallback step.
• Sibling locales are never parents. Menu_es_ES contributes nothing to an es_MX lookup.
• A fallback result keeps its own chain. If the search lands on Menu_de_DE, keys missing there come from Menu_de, then Menu.
• keySet() and containsKey() cover the whole chain; only the protected handleKeySet() is limited to the bundle's own keys.

java.util.MissingResourceException is thrown in two situations: by getBundle when no candidate exists at all (it never returns null or an empty bundle), and by getString/getObject when the key is absent from the bundle and every parent. It extends RuntimeException, so the compiler never forces you to catch it; getKey() on the exception returns the missing key.

A bundle can be a .properties file, loaded as a PropertyResourceBundle whose values are always Strings, or a class that extends ListResourceBundle and returns an Object[][] of key–value pairs from getContents(), whose values can be any object. When both exist for the same candidate name (a class Tips_fr and a file Tips_fr.properties), the default ResourceBundle.Control tries the class format first, so the class wins and the file is ignored.

A properties file containing retries=3 therefore yields the String "3" from getObject (and "3".equals(3) is false, because an Integer is never equal to a String), while a class can store a real Integer.

import java.util.ListResourceBundle;

public class Quota extends ListResourceBundle {
    @Override
    protected Object[][] getContents() {
        return new Object[][] {
            {"retries", 3},
            {"colors", new String[] {"red", "green", "blue"}}
        };
    }
}

import java.util.*;

public class Main {
    public static void main(String[] args) {
        var rb = ResourceBundle.getBundle("Quota", Locale.UK);
        Integer retries = (Integer) rb.getObject("retries");
        String[] colors = rb.getStringArray("colors");
        System.out.println(retries * 5 + " " + colors[2]);
        System.out.println(rb.getString("retries"));
    }
}

Run with java -cp out Main after compiling both classes, this prints 15 blue and then throws ClassCastException at getString("retries"): the value is an Integer, and getString casts it to String.

java.text.MessageFormat fills numbered placeholders {0}, {1}… in a pattern with arguments, formatting each one for a locale, so that translators can reorder and repeat arguments in a pattern stored in a resource bundle without changing code. The static MessageFormat.format(pattern, args…) uses the FORMAT default locale; new MessageFormat(pattern, locale) fixes one.

Placeholder rules

• The index refers to the argument position, not the order in the pattern; an index can appear several times.
• A placeholder with no matching argument is printed literally (such as {2}), not as null and without an exception.
• A single quote starts a quoted (literal) section and is not printed, so Don't stop {0} prints Dont stop {0}: the placeholder is swallowed. Write two quotes (Don''t) for one apostrophe. A backslash is not an escape character here.
• A plain {0} formats a Number with the locale's number format (grouping included), a Date with a date-time format, and anything else (including a String or a LocalDate) with toString().

Format types and styles

import java.text.MessageFormat;
import java.util.Locale;

public class Main {
    public static void main(String[] args) {
        Locale.setDefault(Locale.UK);
        System.out.println(MessageFormat.format(
            "{0} meets {1}; {1} thanks {0}", "Raj", "Mia"));
        System.out.println(MessageFormat.format(
            "{0} booked {1} seats on {2}", "Omar", 4321));
        System.out.println(MessageFormat.format(
            "Don't stop {0}", "Omar"));
        System.out.println(MessageFormat.format(
            "Don''t stop {0}", "Omar"));
        System.out.println(MessageFormat.format(
            "{0,number,percent} {1,number,integer}", 0.738, 4.5));
        String p = "{0,choice,0#an empty cart|1#a single item"
            + "|1<{0,number,integer} items}";
        for (int n : new int[] {0, 1, 5}) {
            System.out.print(MessageFormat.format(p, n) + "; ");
        }
        System.out.println();
    }
}

Output, line by line: Raj meets Mia; Mia thanks Raj; Omar booked 4,321 seats on {2}; Dont stop {0}; Don't stop Omar; 74% 4; an empty cart; a single item; 5 items; . To show a java.time value in a message, format it with a DateTimeFormatter first and pass the String.

Parsing messages

A MessageFormat also works in reverse: parse(String) matches the text against the pattern and returns an Object[] of the parsed arguments, indexed like the placeholders. Plain {n} elements come back as Strings and {n,number} elements as a Long or Double. It declares the checked ParseException, thrown when the text does not fit the pattern (the message is MessageFormat parse error!).

import java.text.*;
import java.util.*;

public class Main {
    public static void main(String[] args)
            throws ParseException {
        var mf = new MessageFormat(
            "{0} owes {1,number}", Locale.UK);
        Object[] parts = mf.parse("Omar owes 18.75");
        System.out.println(parts[0] + " | " + parts[1] + " "
            + parts[1].getClass().getSimpleName());
    }
}

This prints Omar | 18.75 Double.

java.text.NumberFormat is the locale-aware formatter for numbers, and its static factories return a ready-made format for a locale (or for the FORMAT default when no locale is passed). The locale decides the symbols: the US and UK group with a comma and use a decimal point (54,321.6), Germany and the Netherlands do the reverse (5.432,1).

Rounding is HALF_EVEN in every NumberFormat and DecimalFormat: an exact tie goes to the even neighbour, so 4.5 → 4, 5.5 → 6, 0.625 → 0.62 at two digits, and both 3,500 and 4,500 become 4K. Only exact binary ties count (0.625 and 4.25 are exact; many decimal fractions are not). setRoundingMode changes it.

• setMinimumFractionDigits(2) pads 7 to 7.00 but leaves the maximum at 3, so 2.71828 still prints 2.718. A minimum above the maximum raises the maximum to match (and vice versa).
• Percent formats expect a ratio: passing 40 prints 4,000%.
• The UK and US currency formats write negatives with a leading minus, not parentheses (the accounting style is a separate variant).
• setCurrency(Currency.getInstance("EUR")) swaps the symbol but keeps the locale's layout, so a UK instance formats 88.4 as €88.40. It does not adjust the fraction digits for you.
• Compact SHORT English styles use K, M and B and leave numbers below 1,000 unchanged (640); after setMaximumFractionDigits(1), 2,250 and 2,350 print 2.2K and 2.4K.

import java.text.NumberFormat;
import java.util.*;

public class Main {
    public static void main(String[] args) {
        var uk = Locale.UK;
        var nl = Locale.of("nl", "NL");
        System.out.println(NumberFormat.getInstance(uk)
            .format(4321.98765));
        System.out.println(NumberFormat.getInstance(nl)
            .format(5432.1));
        System.out.println(NumberFormat.getIntegerInstance(uk)
            .format(4.5));
        System.out.println(NumberFormat.getCurrencyInstance(uk)
            .format(-7.5));
        System.out.println(NumberFormat.getCurrencyInstance(uk)
            .format(0.625));
        System.out.println(NumberFormat.getPercentInstance(uk)
            .format(0.738));
        var shortF = NumberFormat.getCompactNumberInstance(
            uk, NumberFormat.Style.SHORT);
        var longF = NumberFormat.getCompactNumberInstance(
            uk, NumberFormat.Style.LONG);
        System.out.println(shortF.format(3_500) + " "
            + shortF.format(4_500) + " " + longF.format(7_000_000));
    }
}

This prints 4,321.988, 5.432,1, 4, -£7.50, £0.62, 74% and 4K 4K 7 million.

NumberFormat.parse(String) reads the longest number it can from the start of the text using the locale's symbols, ignores whatever follows, and returns a Number: a Long when the value is integral and fits, otherwise a Double. It throws the checked java.text.ParseException only when the text does not begin with a parsable number, so code that calls it must catch or declare ParseException (parseObject declares the same exception).

import java.text.*;
import java.util.Locale;

public class Main {
    public static void main(String[] args)
            throws ParseException {
        var uk = NumberFormat.getInstance(Locale.UK);
        var nl = NumberFormat.getInstance(Locale.of("nl", "NL"));
        var whole = NumberFormat.getIntegerInstance(Locale.UK);
        show(uk.parse("7.75 litres"));
        show(uk.parse("8.0"));
        show(nl.parse("8,25.1"));
        show(whole.parse("99.9"));
        show(NumberFormat.getCurrencyInstance(Locale.UK)
            .parse("£3.40"));
    }

    static void show(Number n) {
        System.out.println(n + " "
            + n.getClass().getSimpleName());
    }
}

The program prints 7.75 Double (parsing stops at the space before litres), 8 Long (8.0 is integral), 8.25 Double (in Dutch the comma is the decimal separator and the point after it ends the number), 99 Long (an integer instance stops at the decimal separator; parsing never rounds) and 3.4 Double (a currency instance expects and consumes the symbol). Parsing "3.40" with that currency instance would throw ParseException, because the required £ prefix is missing.

DecimalFormat formats with an explicit pattern, while the locale supplies only the symbols through DecimalFormatSymbols. In the pattern, 0 is a required digit (padded with zeros), # is an optional digit (dropped when zero), , marks the grouping size, . the decimal separator, % multiplies by 100, and a ; introduces a negative subpattern whose prefix and suffix replace the minus sign (its digits are ignored).

String.format, "…".formatted(…), printf and java.util.Formatter are a separate engine with its own rules. Without a Locale argument they use the FORMAT default (formatted has no locale parameter at all); String.format(Locale.UK, …), printf(Locale.JAPAN, …) and new Formatter(locale) override it. In %,.2f the , flag turns on grouping and .2 is the precision; %,2f is a width of 2 with the default precision of six. %d with a double throws IllegalFormatConversionException. Formatter rounds HALF_UP (6.25 → 6.3 with %.1f), unlike DecimalFormat, which would give 6.2.

String concatenation of a double calls Double.toString, which is never localized.

import java.text.*;
import java.util.*;

public class Main {
    public static void main(String[] args) {
        var uk = DecimalFormatSymbols.getInstance(Locale.UK);
        var nl = DecimalFormatSymbols.getInstance(
            Locale.of("nl", "NL"));
        System.out.println(new DecimalFormat("0.00", uk).format(0.7)
            + " " + new DecimalFormat("#.##", uk).format(0.7));
        System.out.println(new DecimalFormat("00.#", uk).format(4.25));
        System.out.println(new DecimalFormat("#,##0.00", nl)
            .format(87654.321));
        System.out.println(new DecimalFormat("#,##0.0;[#,##0.0]", uk)
            .format(-98765.25));
        System.out.println(new DecimalFormat("#%", uk).format(0.738));
        Locale.setDefault(Locale.of("nl", "NL"));
        double total = 5432.1;
        System.out.println(total + " " + "%.1f".formatted(6.25) + " "
            + String.format("%,d", 98765) + " "
            + String.format(Locale.UK, "%,.2f", total));
    }
}

Output: 0.70 0.7, 04.2, 87.654,32, [98,765.2], 74%, then, with the Netherlands as the default, 5432.1 6,3 98.765 5,432.10.

java.time.format.DateTimeFormatter formats and parses java.time values either from a pattern (ofPattern) or from a locale's built-in style (ofLocalizedDate, ofLocalizedTime, ofLocalizedDateTime with a FormatStyle). Formatters are immutable and thread-safe; withLocale returns a copy. ofPattern(p, locale) or .withLocale(locale) decides the language of month and day names; without one, the FORMAT default is used.

Pattern letters

The pattern is just a String, so mistakes compile. Using mm where MM was meant silently prints minutes; asking a LocalDate for an hour or minute (HH, mm) throws UnsupportedTemporalTypeException when formatting.

Localized styles

Each locale has its own text for the four FormatStyles. For Locale.CANADA the date styles of 4 June 2027 are FULL Friday, June 4, 2027, LONG June 4, 2027, MEDIUM Jun 4, 2027 and SHORT 2027-06-04; SHORT is 6/4/27 for Locale.US and 04/06/2027 for Locale.UK, which put day and month in opposite orders. Date-only styles never need a zone, and ofLocalizedDate formats just the date part of a LocalDateTime. The LONG and FULL time styles print a time-zone name, so applying ofLocalizedTime or ofLocalizedDateTime with those styles to a LocalDateTime throws DateTimeException: Unable to extract ZoneId. Use a ZonedDateTime or the SHORT/MEDIUM styles.

Parsing and resolver styles

LocalDate.parse(text) uses ISO_LOCAL_DATE, which needs exactly uuuu-MM-dd ("2027-6-4" fails) and is STRICT. A pattern formatter defaults to SMART, which clamps an out-of-range day to the month's last day; withResolverStyle can change it. All parsing failures are the unchecked DateTimeParseException.

With STRICT, use uuuu: yyyy is year-of-era, and without an era field (G) it cannot be resolved, so even a valid date fails. Parsing month names needs the right locale and width: "4 Dezember 2027" parses with d MMMM uuuu and a German locale (Locale.GERMANY or Locale.GERMAN), but not with MMM (which expects the short form Dez.), not with dd (the day has one digit) and not with an English locale.

import java.time.*;
import java.time.format.*;
import java.util.Locale;

public class Main {
    public static void main(String[] args) {
        var when = LocalDateTime.of(2027, 6, 4, 21, 8);
        var f = DateTimeFormatter.ofPattern(
            "EEEE dd/MM 'from' hh:mm a", Locale.UK);
        System.out.println(when.format(f));
        System.out.println(when.format(
            DateTimeFormatter.ofPattern("dd/mm/uuuu")));
        for (var s : FormatStyle.values()) {
            System.out.println(s + ": " + when.format(DateTimeFormatter
                .ofLocalizedDate(s).withLocale(Locale.CANADA)));
        }
        System.out.println(when.format(DateTimeFormatter
            .ofLocalizedDate(FormatStyle.MEDIUM)
            .withLocale(Locale.US)));
        var smart = DateTimeFormatter.ofPattern("uuuu-MM-dd");
        System.out.println(LocalDate.parse("2027-04-31", smart));
        System.out.println(LocalDate.parse("2027-04-31", smart
            .withResolverStyle(ResolverStyle.LENIENT)));
        try {
            LocalDate.parse("2027-04-31");
        } catch (DateTimeParseException e) {
            System.out.println(e.getMessage());
        }
        try {
            LocalDate.parse("2027-04-30", DateTimeFormatter
                .ofPattern("yyyy-MM-dd")
                .withResolverStyle(ResolverStyle.STRICT));
        } catch (DateTimeParseException e) {
            System.out.println("yyyy STRICT fails");
        }
        try {
            DateTimeFormatter.ofLocalizedTime(FormatStyle.LONG)
                .withLocale(Locale.UK).format(when);
        } catch (DateTimeException e) {
            System.out.println(e.getMessage());
        }
    }
}

Output: Friday 04/06 from 09:08 pm, 04/08/2027 (the minute bug: 8 minutes past, not August), the four Canadian styles, Jun 4, 2027, 2027-04-30, 2027-05-01, the STRICT message, yyyy STRICT fails, and Unable to extract ZoneId from temporal 2027-06-04T21:08.