Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Internationalization steps
Now let's turn to the actual steps for internationalizing your Eclipse plug-in:
Use proper locale-sensitive data formatting, substitutions APIs
Prepare and send domestic language materials for translation
We'll discuss each of these steps in detail.
Step 1. Move translatable strings into *.properties files
Fortunately, Eclipse's Java Development Tooling provides considerable help to properly separate translatable strings. The Find Strings to Externalize choice from a package context menu displays the Externalize Strings wizard. This wizard will lead you through the steps to locate hardcoded strings in your code, classify them as translatable or not, then modify the code to use a resource bundle where appropriate.
We'll introduce the Externalize Strings wizard with an example, the canonical "Hello World" before using the wizard:
Listing 3. Hello world, before translation
package com.jumpstart.nls.example.helloworld;
public class HelloWorld {
static public void main(String[] args) {
System.out.println("Copyright (c) IBM Corp. 2002.");
System.out.println("Hello.");
System.out.println("How are you?");
System.out.println("Goodbye.");
}
}
Selecting Find Strings to Externalize from the package context menu will display a selection dialog of all the compilation units in the package that may contain translatable text. Since we only have one Java file at this time, selecting Externalize Strings directly from the HelloWorld.java file is easier. It displays the Externalize Strings wizard:
)
Figure
1. Externalize Strings wizard
By selecting an entry from the table and then one of the pushbuttons to the right, you can mark the strings as belonging to one of three cases:
TranslateAction: An entry is added in the properties files; the auto-generated key and access code is substituted in the code for the original string. The string used to specify the key is marked as non-translatable with a comment marker, such as "// $NON-NLS-1$"
Never TranslateAction: The string is marked as non-translatable with a comment marker. The Externalize Strings wizard will not flag it as untranslated in subsequent executions.
SkipAction: Nothing is modified. Subsequent executions of the Externalize Strings wizard will flag the string as potentially translatable.
NOTE
The trailing number in the // $NON-NLS-1$ comment marker indicates which string is not to be translated in the case where are there are several strings on a single line. For example:
x.foo("Date", "TOD", "Time"); // $NON-NLS-2$
Here the middle parameter is flagged as non-NLS. The other two are skipped.
Returning to our example, note that the total number of strings for each category is summarized below the list. The key names of the externalized strings are auto-generated based on the string value, but they can be renamed directly in the table. In addition, an optional prefix can be specified (S_ in the example below).
)
Figure
2. Externalize Strings wizard
Hint
Clicking the icon in the first column of a given row will advance to the next choice: Translate, Never Translate, or Skip.
Now that we've identified what strings are translatable, continue to the next step to choose how they will be externalized. Here's the page displayed after selecting Next; the Property file name and resource bundle accessor Class name were modified to more specific values than the defaults:
)
Figure
3. Externalize Strings wizard
The resource bundle accessor class will contain code to load the properties file and a static method to fetch strings from the file. The wizard will generate this class, or you can specify your own existing alternative implementation. In the latter case, you may want to uncheck the Use default substitution choice and specify an alternative code pattern for retrieving externalized strings. If the accessor class is outside of the package (for example, a centralized resource bundle accessor class), you can optionally specify that you want to Add [an] import declaration to the underlying source.
The Externalize Strings wizard uses the JDT Refactoring framework, so the next two pages should look familiar. First, a list of warnings:
)
Figure
4. Externalize Strings wizard
And finally a side-by-side presentation of the proposed changes:
)
Figure
5. Externalize Strings wizard
Once you select Finish, the wizard performs the source code modifications, creates the resource bundle accessor class, and generates the initial properties file. Here is the code for the standard resource bundle accessor class:
Listing 4. Standard resource bundle accessor class
package com.jumpstart.nls.example.helloworld;
import java.util.MissingResourceException;
import java.util.ResourceBundle;
public class HelloWorldMessages {
private static final String BUNDLE_NAME =
"com.jumpstart.nls.example.helloworld.HelloWorld"; //$NON-NLS-1$
private static final ResourceBundle RESOURCE_BUNDLE =
ResourceBundle.getBundle(BUNDLE_NAME);
private HelloWorldMessages() {}
public static String getString(String key) {
try {
return RESOURCE_BUNDLE.getString(key);
} catch (MissingResourceException e) {
return '!' + key + '!';
}
}
}
The only variation in this generated code is the value assigned to the static final, BUNDLE_NAME. Before we continue to the next step, below are some noteworthy guidelines contributed by Erich Gamma and Thomas Mäder of the JDT team.
Guidelines for managing resource bundles and properties files
These guidelines are designed to:
Reduce the number of NLS errors, in other words, the values of externalized strings that are not found at runtime
Enable cross-referencing between the keys referenced in the code and the keys defined in the properties file
Simplify the management of the externalized strings. Using a centralized property file can result in frequent change conflicts. In addition, it requires the use of prefixes to make keys unique and complicates the management of the keys.
To achieve these goals, we propose the following guidelines:
Use a properties file per package, and qualify the keys by class name
Use a dedicated static resource bundle accessor class
Do not use computed keys
-
The convention for the key name is <classname>.<qualifier>
For example, all the strings for the JDT search component are in SearchMessages.properties, with key/value pairs like:
SearchPage.expression.pattern=(? = any character, * = any string) ShowTypeHierarchyAction.selectionDialog.title=Show in Type Hierarchy
Let the Externalize Strings wizard generate this class. It should be named like the properties file. So in our example, it would be called SearchMessages. When you need to create formatted strings, add the convenience methods to the bundle accessor class. For example:
Listing 5. Static resource bundle accessor class
public static String getFormattedString(String key, Object arg) {
String format= null;
try {
format= RESOURCE_BUNDLE.getString(key);
} catch (MissingResourceException e) {
return "!" + key + "!";//$NON-NLS-2$ //$NON-NLS-1$
}
if (arg == null)
arg= ""; //$NON-NLS-1$
return MessageFormat.format(format, new Object[] { arg });
}
public static String getFormattedString (String key, String[] args) {
return MessageFormat.format(RESOURCE_BUNDLE.getString(key), args);
}
There is no easy way to correlate a computed key in the code with the key in the properties file. In particular it is almost impossible to determine whether a key is no longer in use.
Example: PackageExplorerPart.title
Step 2. Separate presentation-dependent parameters
Not all externalized text is simply words and phrases that will be translated to a target language. Some are more specifically related to your plug-in's implementation. Examples include properties, preferences, and default dialog settings.
Here are a few specific examples that might find their way into a properties file:
Size or layout constraints. For example, the appropriate width of a non-resizable table column
-
Default fonts that are dependent on the language or operating system. A good default font for Latin-1 languages is an invalid choice for DBCS languages (see Font related .properties files for more details).
For those plug-ins that subclass from AbstractUIPlugin, NL-related parameters can also be found in its default preference stores (pref_store.ini) and dialog settings (dialog_settings.xml). The Eclipse Workbench itself does not use default preference stores, opting instead to store defaults in properties files and then initialize them via AbstractUIPlugin's initializeDefaultPreferences(IPreferenceStore) method.
Step 3. Use proper locale-sensitive data formatting, substitutions APIs
Please refer to the detailed coverage in the Java Tutorial: Internationalization trail.
Step 4. Test in domestic language
Testing the readiness of a product for translation is non-trivial and beyond the scope of this article. However, the follow-on article "Testing your internationalized Eclipse plug-in" presents strategies for validating the NL-sensitive aspects of your product.
Step 5. Create initial translated plug-in fragment
At this point, we could simply copy our domestic language property files to similarly named files with locale-specific suffixes (for example, MyMessages_xx.properties, where xx is the language), and move to step 6, Prepare and send domestic language materials for translation. In this case, the product is delivered with its code and whatever languages it supports as a single install.
However, this approach has a few drawbacks. Firstly, the code and its national language resources are intermingled in the same directory / JAR file. If the translation lags the code delivery, the plug-in JAR file must be updated, despite the fact that the underlying code is unchanged. Secondly, files other than property files are not inherently locale-sensitive, so they must be segregated to separate directories for each language (for example, HTML, XML, images).
To address these issues, the Eclipse Platform introduces the notion of another reusable component that complements plug-ins, called a plug-in fragment. A plug-in fragment provides additional functionality to its target plug-in. At runtime, these plug-in contributions are merged along with all dependent fragments. These contributions can include code contributions and contributions of resources associated with a plug-in, like property and HTML files. In other words, the plug-in has access to the fragment's contents via the plug-in's classloader.
How and why to use fragments to provide the translatable information
A plug-in fragment is an ideal way to distribute Eclipse-translated information including HTML, XML, INI, and bitmap files. Delivering translations in a non-intrusive way, the Eclipse Platform translations are packaged in fragment JAR files and are added to existing Eclipse installations without changing or modifying any of the original runtime elements. This leads to the notion of a language pack.
The Eclipse Platform merges plug-in fragments in a way that the runtime elements in the fragment augment the original targeted plug-in. The target plug-in is not moved, removed, or modified in any way. Since the fragment's resources are located by the classloader, the plug-in developer has no need to know whether resources are loaded from the plug-in's JAR file or one of its fragments' JAR files.
Eclipse Language Pack JAR
The Java language supports the notion of a language pack with the resource bundle facility. The Java resource bundles do not require modification of the application code to support another language. The *.properties file namespace avoids collisions through the following naming convention: basename_lang_region_variant. At runtime, the ResourceBundle facility finds the appropriate properties file for the current locale.
The approach to deploying files such as HTML and XML files in fragments is slightly different than Java resource bundles in that the Eclipse fragment uses a directory structure to sort out the different language versions.
Example fragment contents
The plug-ins and the plug-in fragments reside in separate subdirectories found immediately under the eclipse subdirectory. Looking at our example fragment, as deployed on a German system, we see an \nl folder, fragment.xml and an nl1.jar file.
)
Figure
6. Fragments subdirectories
Typically, translated *.properties files are suffixed according to the resource bundle rules and deployed in JAR files. In contrast, when a view needs an input file type whose name is not locale-sensitive like resource bundles (such as *.xml), we define a subdirectory structure for each language version of the file. The de subdirectory above is one such example, where de = German.
Fragment manifest
Each plug-in folder can optionally contain a fragment manifest file, fragment.xml. The manifest file describes the plug-in fragment, and is almost identical to the plug-in manifest (plugin.xml), with the following two exceptions:
The class attribute is gone since fragments do not have a plug-in class. They just follow their target's specification.
There are no dependencies because the fragments have the same dependencies as their target plug-in.
Manifests used to describe a national language fragment are typically quite simple, specifying only the <fragment> and <runtime>/<library> tags. Here's the example fragment manifest file in its entirety:
Listing 6. Fragment manifest file
<?xml version="1.0" encoding="UTF-8"?> <fragment id="com.jumpstart.nls.example.helloworld.nl1" name="NLS Example Plugin NL Support" version="1.0.0" provider-name="IBM" plugin-id="com.jumpstart.nls.example" plugin-version="1.0.0"> <runtime> <library name="nl1.jar"/> <library name="$nl$/"/> </runtime> </fragment>
The <fragment> tag attributes are:
name -- User-displayable name for the extension.
id -- Identifier for this fragment configuration. Used to uniquely identify this fragment instance.
plugin-id -- Reference to the target extension point. This plug-in fragment merges with this target extension.
plugin-version -- Version of the fragment plug-in.
version -- Version specification in major.minor.service format.
The <runtime> section contains a definition of one or more libraries that make up the plug-in fragment runtime. The referenced libraries are used by the platform execution mechanisms where the plug-in loads, merges, and executes the correct code required by the plug-in. Each <library> subtag has a name attribute. It specifies the library file or directory export mask. To include the contents of a folder as well as its subfolders in a library, use the mask $foldername$/ where foldername is the directory that is to be added to the library search path. We will see later how we use this mask to include the \nl folder's contents plus its subfolders' contents.
Building a fragment
The Eclipse Workbench comes with a tool used in plug-in development: the Plug-in Development Environment (PDE). The PDE contains support for developing plug-in fragments.
Let's now examine how to build a fragment for national language translations using the PDE. There is no practical limit to the number of languages in a given fragment. The fragment then is the basis of our "Language Pack" containing one or more language translations. However, in this example, we'll confine our language pack to the German translation.
To build a plug-in fragment, start the New Project wizard (File > New > Project...), select the Plug-in Development category, then Fragment Project type. On the first page of the New Fragment Wizard, type the project name. Keep in mind that the project name will also become the fragment ID. For example, starting a project adding national language support to the HelloWorld example, we would name our project "com.jumpstart.nls.example.helloworld.nl1". The trailing ".nl1" is not required, but does help distinguish fragments that represent "language packs" from fragments that add additional code and functionality.
)
Figure
7. Starting a fragment project
Press Next. We see the default values for the project's source folder and runtime library on the second page:
)
Figure
8. Defining fragment folders
These values seem reasonable, so pressing Next again, we arrive at the "Fragment Code Generators" page. Select the second radio button to indicate we want to create the fragment manifest file from a template, then select the Default Fragment Generator wizard from the list.
)
Figure
9. Selecting the default wizard
After pressing Next, we see the "Simple Fragment Content" page. This page has two entries used to target our fragment on an existing plug-in. We must supply the plug-in target id and version. We can use the Browse button to select the plug-in that we want to extend.
)
Figure
10. Targeting the fragment
Now let's proceed to the fragment manifest editor, which is similar to the plug-in manifest editor in that it is a multi-page editor with Overview, Runtime, Extensions, Extension Points, and Source pages.
)
Figure
11. Fragment manifest editor
Notice the tabbed pages corresponding to sections of the fragment xml file. We will be using the Runtime page to point the fragment classpath at the libraries containing our translations.
We specified the nl1.jar in the new fragment wizard so that library is already included in the classpath of this fragment. What is missing at this point is the inclusion of the \nl folder plus its subfolders' contents. You can add new runtime libraries by selecting More from the Runtime Libraries section of the Overview page, or by turning to the Runtime page, selecting New..., then entering the folder mask $foldername$/.
)
Figure
12. Fragment runtime information
Taking a look at the Source page of the fragment manifest editor, we see that the PDE generates all the XML necessary to describe our plug-in fragment.
)
Figure
13. Fragment source
Step 6. Prepare and send domestic language materials for translation
Producing correct translations requires specific skills, which you must purchase. (Unfortunately, your four years of high school German classes do not qualify you!) There are many companies that will gladly produce professional-quality translations.
For the Eclipse Platform, this step was accomplished in two phases. The first phase involved sending all the externalized text to a translation center. This first-pass translation is done "out of context." The translator does not see the running product, nor do they have product-specific experience. They have tools at their disposal to help speed the translations and assure consistency, but ultimately they rely on translation testers to validate the running product in the target language (the second phase).
The risk and consequences of performing an out-of-context translation, the results of which are sometimes quite amusing, are discussed in the follow-on article "Testing your internationalized Eclipse plug-in".
Step 7. Repackage and validate translated materials
Now having the translated files, we reassemble them in their appropriate directories/JAR files as described in step 5, Create initial translated plug-in fragment. The NL1 Fragment folder contains language versions of the plugin.properties file. After translating the HelloWorld.properties file to German, we rename it to HelloWorld_de.properties and store it in the NL1 Fragment source folder. Note that the nl\de (German) folder is new and is created manually, not by the PDE. These language-specific folders segregate the versions of non-properties files (such as hello.xml shown below) as we add translations over time.
)
Figure
14. Reassembled fragment project
Be aware that the translated properties files will very likely contain accented characters that are codepage dependent, so properties files must be converted to the ISO 8859-1 codepage expected by the PropertyResourceBundle class. The native2ascii utility (see Resources) will handle codepage conversions and insert any necessary Unicode escapes.
The term Unicode escape deserves a bit more explanation. The native2ascii conversion utility, included with the Java SDK, accepts a source encoding and produces output encoded in ISO 8859-1, plus it transforms characters outside this codepage to the notation known as Unicode escapes. This notation is \udddd, where dddd = the codepoint of the desired character in the Unicode codepage.
Here's an example. Consider the French phrase "Son père est allé à l'hôtel" (his father went to the hotel). This contains four accented characters that are not part of the Latin-1 codepage. Transforming this phrase with the native2ascii utility yields:
Son p\u00e8re est all\u00e9 \u00e0 h\u00f4tel
There are no longer any accented characters, and the resulting string is composed entirely of characters having codepoints that are found in ISO 8858-1. But what are the \u00e8, \u00e9, \u00e0, and \u00f4 that were substituted? They are the Unicode codepoints of the accented characters in \udddd notation.
A little caveat when using the native2ascii utility: It assumes that the source encoding is the same as the active codepage of the machine that executes it. However, translators typically save the translations in their default country codepage, and this codepage is different in each country and each operating system. So the person responsible for integrating the translations will need to either (a) know in which codepage that the translators save their files, or (b) ask that they save it in a common codepage. You can specify the source encoding when invoking native2ascii with the-encoding parameter.
TIP
If you are uncertain of the source codepage, you can spot-check the output of native2ascii against Table 3. Unicode codepoints of common accented Latin characters later in this article. If you find \udddd notations in your converted files that are not in this table (such as \u0205), it is likely that you specified the incorrect source encoding. There is no equivalent spotcheck for DBCS languages, where practically all the characters in the converted files are Unicode escapes. You simply have to be careful and validate against the running product.
Testing the translation merits its own article. The follow-on article "Testing your internationalized Eclipse plug-in" describes the process and lessons learned during the recent translation verification of the Eclipse Platform, and includes a view (an Eclipse plug-in, of course!) for performing a quick check of property file translations.
Fragment sources, similar to plug-in sources, may be packaged in a JAR file. Using the PDE to generate the JAR package, select the "fragment.xml" file and choose "Create Fragment JARs..." from the pop-up menu. A wizard will guide you in creating a build script to produce all the required JARs for your fragment.
)
Figure
15. Selecting the fragment.xml file
To deploy this example fragment, copy the fragment.xml, the \nl directory, and JAR to the com.jumpstart.example.helloworld.nl1 subdirectory in the plugins directory. This completes our example and the steps for internationalization. The next section covers specifically the translatable elements of the Eclipse Platform, how they are organized, and what is necessary to introduce another language.