Description Ed Burnette 2003-06-02 11:46:21 EDT

1. Internationalization warnings

The Java tools help you to develop applications that can be run on 
international platforms. An important facet of designing a program for use in 
different countries is the localization, or externalization, of text that is 
displayed by the program.

1.1 String externalization

By externalizing strings, the text can be translated for different countries 
and languages without rebuilding the Java program. The JDT provides the 
following support for internationalization and string externalization:

[see online help for current support]

1.2 Character literals

Character literals are sometimes found in Java code and inhibit localization. 
For example, consider this code:

   // find next token
   for (i = 0; s.charAt(i) != ' '; i++) /* skip */ ; // wrong

The use of a literal blank is suspicious here because different languages may 
use many different characters for white space. Better would be:

   for (i = 0; !Character.isWhitespace(s.charAt(i)); i++) /* skip */ ;

The character literal warning is set to "Ignore" by default.


1.3 String concatenation

Strings are often built up from smaller strings in ways that may be natural to 
the programmer but don't match the order the user is used to in their 
localized language. For example, suppose you are trying to internationalize 
this line:

   System.out.println("Choose the " + (choice == RED ? "red" : "blue") + " 
pill"); // wrong


A naïve attempt to do this might be:

   String blue = bundle.getString("blue.txt"); // defined as "blue"
   String red = bundle.getString("red.txt"); // defined as "red"
   String neo1 = bundle.getString("choose.txt"); // defined as "Choose the"
   String neo2 = bundle.getString("pill.txt"); // defined as "pill"
   System.out.println(neo1 + (choice == RED ? red : blue) + neo2); // wrong


But that doesn't work because you're assuming a certain word order of 
adjectives before nouns and building up a string using concatenation in that 
order. Better would be to use two entirely different messages, or if that's 
not possible then use the Message.Format method with positional substitutions 
like this:

   String blue = bundle.getString("blue.txt"); // defined as "blue"
   String red = bundle.getString("red.txt"); // defined as "red"
   String neo = bundle.getString("choose.pill.txt"); // defined as "Choose the 
{0} pill"
   System.out.println(Message.Format(neo, { (choice == RED ? red : blue) }));

One more rule about concatenated strings. If either or both sides of the 
concatenation are string literals that have been marked as ok, then the 
concatenation is ok too. For example, this will not be considered a violation:

   Class.forName("org.eclipse.swt.internal."+names[i]+".OS"); //$NON-NLS-1$ //
$NON-NLS-2$

The string concatenation warning is set to "Ignore" by default.


1.4 Locale sensitive methods

Certain Java methods were developed before internationalization issues and 
locales were fully understood. Some of them have been deprecated but some 
remain. For example, Date.toString() always returns dates in the form "dow mon 
dd hh:mm:ss zzz yyyy". For example,

   myString = myDate.toString(); // wrong

Better would be to use the DateFormat.format() method like this:

   myString = DateFormat.getDateInstance().format(myDate); 

This will format the date as appropriate for the current locale.

The list of local sensitive methods is configurable. Details TBD.

The locale sensitive method warning is set to "Ignore" by default.


2. Supressing i18n warnings

Some uses of character and string literals, concatenations, and locale 
sensitive methods are ok and some are not. There is no way for the compiler to 
tell which is which. So it allows the programmer to mark the valid uses 
through comments and filters.


2.1 Comments

Comments may be placed in the source code to disable warnings and errors about 
specific code the compiler would otherwise treat as i18n violations. Spaces 
and case are significant in the comments. The /* */ style comments can appear 
anywhere on the line.

    /*I18nOK*/ or //$I18nOK$  - supress all I18n warnings on the line
    /*I18nOK:xx*/ or //$I18nOK:xx$ - same as /*I18nOK*/ - for OneRealm compat.
    //$NON-NLS-n$  - supress the nth non-externalized string warning on the 
line, backward compatible with Eclipse 2.1

2.2 String Filters

Using filters you can reduce the number of non-externalized string warnings 
reported by marking strings that match certain patterns to be ok. The 1.4 (?)
regex syntax is used. This is just a convenience - you could also mark them as 
ok with comments. For example, if you wanted to treat any strings that look 
like XML as ok you might use a filter like:

   <[A-ZA-z][A-Za-z0-9]*>

and then the following line of code would not be marked as an i18n violation 
whether or not it had a supression comment

   s.append("<html>");

Details TBD

2.3 Safe methods

Designating some methods as safe methods will also reduce the number of 
warnings you get. A safe method is one where string literals may be passed 
safely. The classic example of this is resource access like:

   s = resources.getString("Search.Error.title");

It would be better to put a supression comment on each line where this occurs 
so that the reader of the code will not have to wonder about whether this is 
ok or not. However, if that's not practical, then you can add the getString 
method to the safe methods list.

Details TBD