Message Formatting

Dealing with Concatenated Messages

By stepping through a sample program, in this section we'll demonstrate how to internationalize a concatenated message. The sample program makes use of the MessageFormatclass. The full source code for this program is in the file called MessageFormatDemo.java.

1. Identify the Variables in the Message

The English version of the message we want to internationalize is:

At 1:15 PM on April 13, 1998, we detected 7 spaceships on the planet Mars.
      ^             ^                     ^                           ^
      |             |                     |                           |
     Date          Date                 Number                      String

Notice that we've underlined the variable data, and have identified what kind of objects will represent this data.

2. Isolate the Message Pattern in a ResourceBundle

We're going to store the message in a ResourceBundle named MessageBundle. In the code we'll create the ResourceBundle like this:

ResourceBundle messages =
   ResourceBundle.getBundle("MessageBundle",currentLocale);

This ResourceBundle is backed by a properties file for each Locale. Since our ResourceBundle is called MessageBundle, the properties file for U.S. English is named MessageBundle_en_US.properties. The contents of the MessageBundle_en_US.properties file is as follows:

template = At {2,time,short} on {2,date,long}, we detected {1,number,integer} spaceships on the planet {0}.
planet = Mars

We've specified the pattern on the first line of the properties file. If you compare this pattern with the message text shown in step 1, you'll see that we've replaced each variable in the message text with an argument enclosed in curly braces. Each argument starts with a digit called the argument number, which matches the index of an element in an Object array that holds the argument values. Note that in the pattern, these argument numbers are not in any particular order. You can place the arguments anywhere in the pattern. The only requirement is that the argument number has a matching element in the array of argument values. In the next step, we'll discuss the argument value array, but first, let's look at each of the arguments in the pattern. The following table provides some details about the arguments:

Argument	Description
{2,time,short}	The time portion of a Date object. The "short" style specifies the DateFormat.SHORT formatting style.
{2,date,long}	The date portion of a Date object. The same Date object is used for both the date and time variables. In the Object array of arguments the index of the element holding the Date object is 2.
{1,number,integer}	A Number object, further qualified with the "integer" number style.
{0}	The String in the ResourceBundle that corresponds to the "planet" key.

For a full description of the argument syntax, see the API documentation for the MessageFormatclass.

3. Set the Message Arguments

In the following lines of code, we assign values to each argument in the pattern. The indexes of the elements in the messageArguments array match the argument numbers in the pattern. For example, the element at index 1, which is new Integer(7), corresponds to the {1,number,integer} argument in the pattern. We'll fetch the String objects, which are at elements 0 and 3, from the ResourceBundle with getString, because they must be translated. The array of message arguments is defined as follows:

Object[] messageArguments = {
   messages.getString("planet"),
   new Integer(7),
   new Date()
};

4. Create the Formatter

Next, we create a MessageFormat object. We set the Locale because our message contains Date and Number objects, which should be formatted in a locale-sensitive manner. For example, in U.S. English the date 4/13/98 is in the correct format, but in French the format should be 13/04/98. We'll create the message formatter as follows:

MessageFormat formatter = new MessageFormat("");
formatter.setLocale(currentLocale);

5. Format the Message Using the Pattern and the Arguments

In this step, we'll demonstrate how the pattern, message arguments, and formatter all work together. First, we fetch the pattern String from the ResourceBundle with the getString method. The key to the pattern is "template." We pass the pattern String to the formatter with the applyPattern method. Then, we format the message using the array of message arguments by invoking the format method. The String returned by the format method is ready to be displayed. All of this is accomplished with just two lines of code:

formatter.applyPattern(messages.getString("template"));
String output = formatter.format(messageArguments);

6. Run the Demo Program

Let's see what happens when we run the program for the U.S. English Locale:

% java MessageFormatDemo en US

currentLocale = en_US

At 1:15 PM on April 13, 1998, we detected 7 spaceships on the planet Mars.

When running the program with the German Locale, notice that the date and time formats have been localized:

% java MessageFormatDemo de DE

currentLocale = de_DE

Um 13.15 Uhr am 13. April 1998 haben wir 7 Raumschiffe auf dem Planeten Mars entdeckt.

Message Formatting