Internationalization (i18n) and Localization (l10n) in Java

A program written on a computer with English settings ships to a user in Germany, and String.format("%.2f", 1234.5) suddenly returns "1234,50" instead of "1234.50". The next call to Double.parseDouble on that string fails with a NumberFormatException. To avoid surprises like this, an application has to be prepared in advance for different languages and regions. That is what internationalization and localization are for.

Internationalization (i18n) is designing an application so that adding a new language doesn't require recompiling and rebuilding it. UI texts are stored outside the code, in properties files loaded at runtime, and number, date and currency formats come from the current locale instead of being hard-coded.

Localization (l10n) is adapting an application to a specific language and region: translating the UI and documentation, and setting up date, time, currency and number formats and other regional conventions.

What i18n and l10n mean

i18n is an abbreviation of the word internationalization: the first letter i, the last letter n, and 18 letters in between. l10n shortens localization the same way: l, 10 letters, n. Such abbreviations are called numeronyms. Developers came up with them to avoid typing long words in full (you will also see the spelling internationalisation in British English, which gives the same i18n).

In Java, one set of classes covers both tasks, and they are tied together by the locale: a java.util.Locale object, which is a pair of language and region such as en-US or de-DE.

Internationalization vs localization

Internationalization (i18n) is done once, during development: the programmer prepares the code so that it can be translated. Localization (l10n) is done for each language separately: a translator or developer adds translations and regional settings without touching the code. Without i18n, localization turns into rewriting the program.

What changes from locale to locale

A locale affects more than the interface language. It changes number separators, the order of date parts, month names, the currency symbol and its position, the first day of the week and the sort order of strings. The table shows how the same data looks in three locales with the standard Java 11+ formatters.

Java tools for internationalization

Internationalization in Java needs no third-party libraries: the standard library has everything. The foundation is Locale (which language and region) and ResourceBundle (where the translations live). The other classes format numbers, dates and messages by the rules of the chosen locale. This lesson only shows what each class is for, without going into its API.

Frameworks build on the same ideas. For example, Spring Boot internationalization is based on MessageSource, which reads the same messages_xx.properties files and picks the language from the Accept-Language header of the request.

How to internationalize an application: 4 steps

Internationalizing a Java application comes down to four steps. Move all UI strings out of the code into properties files. Set the user's locale explicitly. Load translations through ResourceBundle. Print numbers and dates only through formatters that use that locale.

1. Extract the texts. Instead of System.out.println("Welcome!"), use a key such as message.welcome defined in messages.properties, messages_de_DE.properties and so on.
2. Determine the locale. Take it from user settings, an HTTP request header or Locale.getDefault().
3. Load the translations. ResourceBundle.getBundle("messages", locale) finds the matching file itself. If there is no file for that locale, it falls back to a more general one.
4. Format with the locale. Print numbers, currencies and dates through NumberFormat, DateTimeFormatter and MessageFormat with the same locale instead of concatenating strings by hand.

Here is a Java localization example for dates: the same LocalDate is printed in three locales without changing the code.

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.Locale;

public class LocalizedDateExample {
    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2026, 3, 8);
        Locale[] locales = {Locale.US, Locale.GERMANY, Locale.forLanguageTag("ru-RU")};

        for (Locale locale : locales) {
            DateTimeFormatter formatter = DateTimeFormatter
                    .ofLocalizedDate(FormatStyle.LONG)
                    .withLocale(locale);
            System.out.println(locale.toLanguageTag() + ": " + date.format(formatter));
        }
    }
}
// Output (Java 11+):
// en-US: March 8, 2026
// de-DE: 8. März 2026
// ru-RU: 8 марта 2026 г.

To add French, just put Locale.FRANCE into the array. No format strings or month names appear in your code: the JDK supplies them. That is exactly what internationalization buys you.

Where the default locale breaks your code

If you don't pass a locale, many Java methods use Locale.getDefault(), that is, the settings of the operating system or the JVM. As a result, the same code behaves differently on a developer's machine and on a server. Process internal data (keys, identifiers, file formats) with Locale.ROOT, and apply the user's locale only to text the user will see.

Mistake 1: a number that can't be read back. This is the example from the start of the lesson.

Locale.setDefault(Locale.GERMANY);

String s = String.format("%.2f", 1234.5);
System.out.println(s);                       // Output: 1234,50
double d = Double.parseDouble(s);            // NumberFormatException: For input string: "1234,50"

// Fix: pass Locale.ROOT explicitly for machine-readable output
String fixed = String.format(Locale.ROOT, "%.2f", 1234.5);
System.out.println(fixed);                   // Output: 1234.50
System.out.println(Double.parseDouble(fixed)); // Output: 1234.5

Mistake 2: what does this code print?

Locale tr = Locale.forLanguageTag("tr-TR");

System.out.println("title".toUpperCase(tr));          // Output: TİTLE
System.out.println("TITLE".toLowerCase(tr));          // Output: tıtle
System.out.println("title".toUpperCase(Locale.ROOT)); // Output: TITLE

In Turkish, the lowercase i has a dotted uppercase form (İ), and the uppercase I has a dotless lowercase form (ı). If the application runs with the Turkish default locale, "title".toUpperCase() without arguments returns "TİTLE". Then an equals("TITLE") comparison, a Map key lookup or command parsing quietly stops working. For keys, enum names and protocols, use toUpperCase(Locale.ROOT) or equalsIgnoreCase.