11.4 Internationalization and Localization: `Locale`, `ResourceBundle`, and Formatters

11.4 Internationalization and Localization: Locale, ResourceBundle, and Formatters

Internationalization (I18N) is the process of designing software so that it can adapt to various languages and regions without engineering changes. Localization (L10N) is the adaptation of that software for a specific geographic or cultural market by translating text and formatting numbers, currencies, dates, and times according to regional conventions. Java SE 17 provides comprehensive localization support through java.util.Locale, java.util.ResourceBundle, java.text.NumberFormat, and java.time.format.DateTimeFormatter.

---

The Locale Class and Construction

A java.util.Locale object represents a specific geographic, political, or cultural region. It is composed of:

1. Language Code: Mandatory, 2 or 3 lowercase letters conforming to ISO 639 (e.g., en for English, fr for French, de for German, ja for Japanese).
2. Country / Region Code: Optional, 2 uppercase letters conforming to ISO 3166 or 3 digits conforming to UN M.49 (e.g., US for United States, CA for Canada, DE for Germany, GB for Great Britain).
3. Variant / Script: Optional additional markers (e.g., script Latn or variant POSIX).

Instantiation Approaches in Java SE 17

// 1. Static Constants (Predefined for common languages and nations)
Locale loc1 = Locale.US;       // Language: en, Country: US
Locale loc2 = Locale.GERMAN;   // Language: de (no country)
Locale loc3 = Locale.GERMANY;  // Language: de, Country: DE

// 2. Public constructors (the standard approach in Java 17)
Locale loc4 = new Locale("fr", "CA"); // Language: fr, Country: CA
Locale loc5 = new Locale("es");       // Language: es

// 3. IETF BCP 47 Language Tag
Locale loc6 = Locale.forLanguageTag("zh-CN");

// 4. Locale.Builder (Fluent configuration)
Locale loc7 = new Locale.Builder()
    .setLanguage("en")
    .setRegion("GB")
    .build();

Inspecting and Setting Defaults

The JVM maintains default locales for the active host environment. Java divides the default locale into two categories:

• Locale.Category.FORMAT: Governs formatting of numbers, currencies, and dates.
• Locale.Category.DISPLAY: Governs localized UI names for languages, countries, and UI strings.

Locale defaultLocale = Locale.getDefault();
Locale formatLocale = Locale.getDefault(Locale.Category.FORMAT);

// Updating defaults
Locale.setDefault(new Locale("fr", "FR"));

---

ResourceBundle Architecture and File Formats

A ResourceBundle manages locale-specific resources (such as translated text messages). Java supports two storage formats for resource bundles:

1. Property Resource Bundles (.properties): Standard flat text files containing key=value pairs. Values are strictly String objects.
2. Class Resource Bundles (.java / .class): Concrete classes extending java.util.ListResourceBundle. They define a getContents() method returning Object[][].

Advantages of Class Bundles

• Can contain any Java object type (such as Color, Icon, or byte[]), whereas .properties files are restricted entirely to strings.
• Values can be computed dynamically at runtime.
• Precedence Rule: If both a .class bundle and a .properties bundle exist with the identical bundle name for a given locale, the .class bundle always takes precedence over the .properties bundle!

// Example Class-Based Bundle: Messages_en.java
public class Messages_en extends ListResourceBundle {
    @Override
    protected Object[][] getContents() {
        return new Object[][] {
            { "welcome", "Welcome to our application!" },
            { "maxItems", 500 } // Can store non-String objects!
        };
    }
}

---

ResourceBundle Resolution Hierarchy and Fallback Rules

When ResourceBundle.getBundle(baseName, targetLocale) is called, the JVM performs a deterministic search across the classpath to locate the best matching bundle.

The Search Order

Assume the application requests bundle base name AppLabels for new Locale("fr", "CA") (French Canadian), and the system default locale is new Locale("en", "US"):

1. AppLabels_fr_CA (Target language + target country)
2. AppLabels_fr (Target language only)
3. AppLabels_en_US (Default locale language + default country)
4. AppLabels_en (Default locale language only)
5. AppLabels (Base bundle with no locale suffix)
6. If none of these files exist on the classpath, Java throws java.util.MissingResourceException.

At each step, Java looks for a .class file first, followed by a .properties file.

Key Fallback Mechanics (The Critical Exam Trap)

Once a bundle file is matched, Java selects that bundle family. When you query a specific key using bundle.getString(key), Java searches that bundle. If the key is missing:

• The lookup searches up the inheritance hierarchy of that matched bundle: fr_CA $\rightarrow$ fr $\rightarrow$ base AppLabels.
• It NEVER falls back to the default locale bundle (en_US or en)!

Matched Bundle Family:
AppLabels_fr_CA  --->  AppLabels_fr  --->  AppLabels (Base)
                                                 |
                                       [MissingResourceException]
(Never crosses over to AppLabels_en_US!)

---

Formatting and Parsing Numbers and Currencies: NumberFormat

The java.text.NumberFormat abstract class formats and parses numbers, percentages, and currencies according to regional conventions.

Factory Methods

Locale us = Locale.US;
Locale germany = Locale.GERMANY;

NumberFormat nfUs = NumberFormat.getInstance(us);
NumberFormat nfDe = NumberFormat.getInstance(germany);

System.out.println(nfUs.format(123456.78)); // 123,456.78 (comma thousands, dot decimal)
System.out.println(nfDe.format(123456.78)); // 123.456,78 (dot thousands, comma decimal)

// Currency Formatting
NumberFormat curUs = NumberFormat.getCurrencyInstance(us);
NumberFormat curDe = NumberFormat.getCurrencyInstance(germany);

System.out.println(curUs.format(49.99)); // $49.99
System.out.println(curDe.format(49.99)); // 49,99 € (comma decimal separator, symbol after a space)

Parsing Behavior and Checked Exceptions

The parse(String) method parses text into a java.lang.Number (Long or Double). It throws a checked java.text.ParseException if parsing fails:

1. Prefix Matching: NumberFormat.parse() begins reading from the start of the string. As soon as it encounters a character that is invalid in the given locale, it stops parsing and returns the number accumulated so far! Trailing unparsed characters are simply ignored.
2. Invalid Initial Character: If the very first non-whitespace characters cannot be parsed into a number, parse() throws ParseException.

NumberFormat nf = NumberFormat.getInstance(Locale.US);
Number val1 = nf.parse("45.67xyz"); // Successfully returns 45.67 (stops at 'x')
Number val2 = nf.parse("1,000 items"); // Successfully returns 1000 (stops at ' ')

// nf.parse("x45.67"); // THROWS java.text.ParseException: Unparseable number: "x45.67"

---

Formatting and Parsing Dates: DateTimeFormatter

The modern java.time.format.DateTimeFormatter replaces legacy SimpleDateFormat. Unlike its predecessor, DateTimeFormatter is immutable and thread-safe.

Predefined and Localized Styles

LocalDateTime ldt = LocalDateTime.of(2026, Month.APRIL, 15, 14, 30);

// Standard localized formatters using FormatStyle
DateTimeFormatter shortDate = DateTimeFormatter.ofLocalizedDate(FormatStyle.SHORT);
DateTimeFormatter mediumTime = DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM);
DateTimeFormatter fullDateTime = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT, FormatStyle.SHORT);

System.out.println(shortDate.format(ldt)); // e.g., 4/15/26 in US

The UnsupportedTemporalTypeException in Formatting

A DateTimeFormatter configured for dates cannot format a time-only object, and vice versa. Mismatches trigger runtime exceptions:

LocalDate date = LocalDate.of(2026, Month.APRIL, 15);
DateTimeFormatter timeFormatter = DateTimeFormatter.ofLocalizedTime(FormatStyle.SHORT);

// COMPILES! But throws UnsupportedTemporalTypeException at runtime:
// java.time.temporal.UnsupportedTemporalTypeException: Unsupported field: ClockHourOfAmPm (in a US locale, whose SHORT time pattern is h:mm a)
String output = timeFormatter.format(date); 

Custom Patterns: ofPattern(String)

Custom patterns use case-sensitive symbols:

DateTimeFormatter dtf = DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm");
String formatted = dtf.format(ldt); // "15/04/2026 14:30"

// Parsing strings into temporal objects:
LocalDate parsedDate = LocalDate.parse("15/04/2026", DateTimeFormatter.ofPattern("dd/MM/yyyy"));
// Note: LocalDate.parse() throws unchecked DateTimeParseException if parsing fails!