Contents

A Checklist for Internationalizing an Existing Program

Many programs are not internationalized when first written. These programs may have started as prototypes, or perhaps they were not intended for international distribution. If you need to internationalize an existing program, you should perform the following tasks:

• Identify Culturally Dependent Data

  Text messages are the most obvious form of data that varies with culture, because they must be translated. However, there are other types of data that may vary with region or language. The following list contains examples of culturally dependent data:

  • messages
  • labels on GUI componenets
  • online help
  • sounds
  • colors
  • graphics
  • icons
  • dates
  • times
  • numbers
  • currencies
  • measurements
  • phone numbers
  • honorifics and titles
  • addresses
  • page layouts

  For more information, see Culturally Sensitive Data

• Isolate Translatable Text in Resource Bundles

  Translation is costly. You can help reduce costs by isolating the text that must be translated into ResourceBundle objects. Translatable text includes status messages, error messages, log file entries, and GUI component labels. This text is hardcoded into programs that haven't been internationalized. You'll need to locate all occurrences of hardcoded text that is displayed to end-users. For example, you'll need to clean up code like this:

  String buttonLabel = "OK";
  ...
  Button okButton = new Button(buttonLabel);
  

  See Isolating Locale-specific Objects in a ResourceBundle for details.

• Deal with Compound Messages

  Compound messages contain variable data. In the message, "The disk contains 1100 files," the integer 1100 may vary. This message is hard to translate because the position of the integer in the sentence is not the same in all languages. The following message is not translatable, because the order of the sentence elements is hardcoded by concatenation:

  Integer fileCount;
  ...
  String diskStatus = "The disk contains " + fileCount.toString() + " files.";
  

  Whenever possible, you should avoid constructing compound messages because they are difficult to translate. However, if your application requires compound messages you can handle them with the techniques described in Message Formatting.

• Format Numbers and Currencies

  If your application displays numbers and currencies, you'll need to format them in a locale-independent manner. The following code is not yet internationalized, because it will not display the number correctly in all countries:

  Double amount;
  TextField amountField;
  ...
  String displayAmount = amount.toString();
  amountField.setText(displayAmount);
  

  You'll want to replace the preceeding code with a routine that formats the number correctly. The Java programming language provides several classes that format numbers and currencies. These classes are discussed in the section, Number and Currency Formatting.

• Format Dates and Times

  Date and time formats differ with region and language. If your code contains statements like the following, you'll need to change it:

  Date currentDate = new Date();
  TextField dateField;
  ...
  String dateString = currentDate.toString();
  dateField.setText(dateString);
  

  If you use the date formatting classes, your application can display dates and times correctly around the world. For examples and instructions, see Date and Time Formatting.

• Handle Exception Messages

  You should shield your end-users from the exception messages that are hardcoded in U.S. English. The section Working with Exceptions shows you how to deal with this problem.

• Compare Strings Properly

  When sorting or searching for text, you'll need to compare strings. If the text is displayed, you shouldn't use the comparison methods of the String class. A program that hasn't been internationalized might compare strings as follows:

  String target;
  String candidate;
  ...
  if (target.equals(candidate)) {
  ...
  if (target.compareTo(candidate) < 0) {
  ...
  

  The String.equals and String.compareTo methods perform binary comparisons, which are ineffective when sorting and searching in some languages. Instead, you should use the Collator class, which is described in the section Comparing Strings .

• Use Unicode Character Attributes

  Developers accustomed to programming in other languages might determine a character's attributes by comparing it with character constants. For instance, they might write code like this:

  char ch;
  ...
  if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z')) {
    // ch is a letter
  ...
  if (ch >= '0' && ch <= '9') {
    // ch is a digit
  ...
  if ((ch == ' ') || (ch == '\n') || (ch == '\t')) {
    // ch is a whitespace
  

  This type of code won't work for all languages. You should replace these hardcoded character comparisons with calls to methods provided by the Characterclass. For example, you could replace preceeding code with the following statements:

  char ch;
  ...
  if (Character.isLetter(ch)) {
  ...
  if (Character.isDigit(ch)) {
  ...
  if (Character.isSpaceChar(ch)) {
  
  

• Convert Non-Unicode Text

  Characters in the Java programming language are encoded in Unicode. If your application handles non-Unicode text, you must translate it into Unicode. For more information, see Converting Non-Unicode Text.

• Allow Room for Growth in a GUI

  Text usually expands when translated from English into other languages. Also, character widths are not the same for all character sets and fonts. If your application has a crowded interface it may be impossible to localize. Be sure to design your GUI with room to spare.

Contents