Java Internationalization: Overview

Jakob Jenkov
Last update: 2014-06-23

Internationalizing a Java application typically means making the application able to handle multiple languages, number formats, date formats etc. This text gives you an overview of these aspects.

Basically, your application should be able to handle international input, output and operations. In other words, your application should be able to adapt itself to input, output and operations specific to different locations and user preferences.

Your application should be able to handle international input and output.
Your application should be able to handle international input and output.

Input and output is a coarse grained categorization of what your application need to handle. Here are the issues your application need to cover, in a bit more detail:

Handling International Input

Input is everything that your application receives from its users, either directly through the user interface, sent to it via service calls (e.g. SOAP or REST calls), imported from files etc. Input includes:

  • Form input including
    • Text (language + character encoding)
    • Number formats
    • Date and time formats and calculations
  • Files received
  • Service calls received

Handling International Output

Output is everything your application is showing or sending to its users, either during the installation process, or during general use. Output includes:

  • Text (language + character encoding)
  • Number and currency formatting
  • Date and time formatting and calculations
  • Character comparisons
  • String comparisons

How many of these aspects your application needs to be able to handle depends on your application.

Keep in mind, that if users can have the application display text etc. to them in their own language, they may also expect that support, emails sent to them, forums, help texts etc. to be in their own language.

Adapting Operations

In addition to adapting to input and output, your application may need to adapt certain internal operations to the users location and preferences. For instance, a web shop may need to add different amounts of VAT to a sale, depending on what country the buyer lives in. An investment calculator may have to take different laws and tax rates into consideration etc.

User Information Needed

In order to properly localize your application to a user you may need one or more of the following:

  • Preferred language
  • Country of residence
  • Current location
  • Preferred time zone

The user should be able to tell what language he or she prefers the application to use. Don't just assume that a user living in a given country want the application localized to that language. For instance, I am from Denmark but I prefer that applications are in english, so I can talk to people all over the world about its features, without having to translate feature names etc. Let the user decide.

The country of residence of a user may impact what features are available to the user, and how these features work. For instance, YouTube doesn't allow anyone to become a YouTube partner. Only users living in certain countries are allowed into that program.

The current location may be interesting to know for some applications, especially for all location based applications. The application may take action based on the users location.

Some applications, like a shared calendar, may need to know the users time zone in order to work properly. An appointment at 10 AM - what time is that in the users country? What time is that in the time zone that e.g. an application server is running in? Is the user temporarily out of the country and need to show all appointments in the time zone of the temporary location?

Application Internationalization Layer

In order to handle internationalization of input and output, your application will have a kind of internationalization layer. Here is a diagram illustrating that:

An application internationalization layer.
An application internationalization layer.

The internationalization layer takes care of converting between the users language and formatting, and the language and formatting used internally in the application. For instance, String's are kept internally in the memory of the JVM as UTF-16. The internationalization layer should convert from whatever character encoding the input comes in (ascii, UTF-8 etc.) and to UTF-16.

The internationalization layer may not look like an abstraction layer sitting between the inner and outer components in your application. Rather, it will most likely be a set of API calls to an internationalization component capable of making the conversions and translations. The layer in your application receiving the input data will call this internationalization API, and pass the converted values on to the core operations.

In order to properly convert the input data the internationalization layer must collect the necessary information about the user. That is, the language, character encoding, number formatting, date formatting, time zone conversions etc. of the input data.

When the application needs to output data, the process is similar. The application decides on what to output, and invoke the internationalization layer to have the output converted to formats suitable for the user. That again includes both language, character encoding, number formatting, date formatting, time zone conversions etc.

In reality, your application may look more like this:

Java internationalization components in an application.
Java internationalization components in an application.

What is going on is something like this:

  1. The input (event or request) reaches an input handler (event handler / request handler) in the application.
  2. The input handler determines the user settings necessary for localization.
  3. The input handler calls the I18n component to obtain localized texts, numbers, dates etc.
  4. The input handler calls the application operations. If user preferences are needed to perform the operations, they are passed to the application operations.

Your application may do internationalization a bit different from this. No worries. There are no right and wrong designs here.

Why an Internationalization Component?

The reason you have an internationalization layer or component is to separate the internationalization code from the rest of the application. You may choose to use Java's built-in internationalization features, or you may use another API like ICU4J. By encapsulating your internationalization code in an I18n component, you can change the API used inside it, without affecting the rest of your application.

Java's Internationalization Classes

Java has a set of built-in classes that can help you handle internationalization of your application. These classes are:

Class Description
Locale The Locale class represents a language and a country or region. A Locale may also represent a certain type of formatting - e.g. date or number formatting.
ResourceBundle The ResourceBundle class can contain localized texts or components (objects). You obtain a ResourceBundle for a specific Locale, and thus obtain texts or objects localized to that Locale.
NumberFormat The NumberFormat class is used to format numbers according to a certain Locale.
DecimalFormat The DecimalFormat class is used to format numbers according to customized formatting patterns. These patterns are also Locale sensitive.
DateFormat The DateFormat class is used to format dates according to a specific Locale.
SimpleDateFormat The SimpleDateFormat class is used to parse and format dates according to custom formatting patterns. These patterns are also Locale sensitive.

Each of these classes are covered in more detail in later texts in this trail.

Jakob Jenkov

Featured Videos

Java ForkJoinPool

P2P Networks Introduction


Java Persistence
Close TOC
All Tutorial Trails
All Trails
Table of contents (TOC) for this tutorial trail
Trail TOC
Table of contents (TOC) for this tutorial
Page TOC
Previous tutorial in this tutorial trail
Next tutorial in this tutorial trail