Globalize your Eclipse RCP application

How your UI can easily support multiple languages

The Eclipse Rich Client Platform (RCP) is gaining wide acceptance in software development. For multinational enterprises, delivering software that supports multiple languages is increasingly important to worldwide customers. In this article, learn how to globalize the user interface (UI) elements in an RCP application, including the window, menu, toolbar, dialog, welcome page, splash screen, and standard Eclipse UI elements. A sample Hello World application walks you through the process.

Wei Wang (wangweiu@cn.ibm.com), Staff Software Engineer, IBM

Wei WangWei Wang joined IBM in September, 2004. Currently he is working on IBM ECM Widgets as a developer. He previously worked as a developer for FileNet BPF development.



Yuan Yao Deng (dengyy@cn.ibm.com), Software Engineer, IBM

Yuan Yao Deng is a developer on ECM Widgets. He has more than five years of experience in Eclipse development.



07 July 2009

Also available in Japanese Vietnamese

Introduction

The Eclipse Rich Client Platform (RCP) has a lot of advantages, such as rapid development, native look and feel, extensibility, and multiple platform support. Many enterprises have adopted RCP for developing their software. For multinational enterprises, delivering software that supports multiple languages is increasingly important for sales to worldwide customers. Globalization is a critical part of RCP software development. Learn how to globalize the UI for an RCP application using a Hello World sample.


Sample application

The sample in this article will globalize a Hello World application with some simple functions. Figure 1 shows the main UI of our Hello World application.

Figure 1. Hello World RCP application
Hello World RCP application

When you click Say Hello in the File menu, there will be a dialog showing "Hello! This is a sample!" When you launch the application or click Welcome in the Help menu, the welcome page will be shown in the main UI, providing some introductory information. Clicking About Hello World from the Help menu provides application and version information. That's it for the functions — very simple.

The Hello World application was created with Eclipse V3.4.1, based on the "RCP application with an intro" template following the plug-in project wizard. Some additional code is required after finishing the wizard. Refer to the source of this sample, which you can download. The focus of this article is globalization, so it will not discuss the code for other functions.

After you finish coding for the Hello World, it can only support English by default. You are going to add multilingual support for this application. The UI elements that need globalization include menu, toolbar, dialog, splash screen, welcome page, plug-in and product information, and the standard Eclipse UI elements.


Common resource bundle

As with other Java™ applications, you need to create a resource bundle for the RCP application. In this sample, the resource bundle is put in the helloworld.resource package and named "custom." The resource bundle file name must follow Java resource bundle naming conventions: <resource_name>_<Language Code>_<Country Code>.properties. For example, custom_fr.properties is the resource bundle for French, and custom_zh_CN.properties is for Simplified Chinese. See Resources for more information about language codes and country codes. Figure 2 shows the resource bundle for the Hello World.

Figure 2. Resource bundle structure
Resource Bundle Structure

Resource bundle files contain key/value pairs. The keys uniquely identify a locale-specific object in the bundle. You need to create one key/value for each UI element you want to globalize. Listing 1 shows the properties file for English.

Listing 1. Content of resource bundle file custom_en.properties
MAIN_WINDOW_TITLE=Hello World
MENU_FILE=&File
MENU_FILE_SAY_HELLO=Say Hello
MENU_HELP=&Help
DIALOG_TITLE=Hello
DIALOG_MESSAGE=Hello! This is a sample!

At this point, you need a utility to read the resource bundle. As shown in Listing 2, the CustomString class provides two functions:

  • setBundle initializes a resource bundle object according to locale.
  • getString returns a value for the given key in a specified language.
Listing 2. Utility for reading resource bundle (CustomString.java)
public class CustomString {
	private static final String BUNDLE_NAME = "helloworld.resource.custom";
	private static ResourceBundle rb = null;

	public static void setBundle(Locale locale) {
		try {
			rb = ResourceBundle.getBundle(BUNDLE_NAME, locale);
		} catch (Exception e) {
			rb = ResourceBundle.getBundle(BUNDLE_NAME, Locale.ENGLISH);
		}
	}

	public static String getString(String key) {
		try {
			String keyValue = new String(rb.getString(key).getBytes(
			        "ISO-8859-1"), "UTF-8");
			return keyValue;
		} catch (Exception e) {
			return key;
		}
	}

}

After the resource bundle and utility are ready, you notify the application regarding what language should be used when it launches. Application.java is the entry of an RCP application. It is recommended that you initialize the resource bundle in the start() method. Locale.getDefault() returns the default system locale, and the returned locale is passed to CustomString.setLocale(), as shown below. The application will initialize the resource bundle using the system locale.

Listing 3. Set locale in Application.java
	public Object start(IApplicationContext context) {
		CustomString.setLocale(Locale.getDefault());
		...
		}

The common resource bundle is available to the whole application now. The next section explains how to invoke the resource bundle in the UI.


Toolbar, menu, and dialog

In an RCP application, menu and toolbar entries are represented with actions. Menu and toolbar can be added by code or extension. Our sample registers menu actions by code. In the action definition class, the action label is defined in the constructor by the setText() method. The text will be displayed as a menu label. As you can see, the text is now hard-coded for English only. The modified code replaces "Say Hello" using the resource bundle in the setText() method.

Listing 4. Set action text in HelloAction.java for menu and toolbar
public HelloAction(IWorkbenchWindow iworkbenchwindow) {
	this.window = iworkbenchwindow;
	this.setText("Say Hello");
	this.setImageDescriptor(WorkbenchImages.
	getImageDescriptor(IWorkbenchGraphicConstants.IMG_VIEW_DEFAULTVIEW_MISC));
	// Must setId,otherwise can not leverage Register method
	setId("helloworld.actions.HelloAction");
	window.getSelectionService().addSelectionListener(this);
	}
	
	/**
	Modified Code
	**/
	public HelloAction(IWorkbenchWindow iworkbenchwindow) {
	....
		this.setText(CustomString.getString("MENU_FILE_SAY_HELLO"));
	....
	}

Dialogs have different code to show text on the UI, but the globalization method is the same. You can use the same approach to globalize other UIs generated by Java code — it's not limited to the menu, toolbar, and dialog.

Listing 5. Set dialog title and message
		MessageDialog.openInformation(PlatformUI.getWorkbench()
				.getActiveWorkbenchWindow().getShell(),
				"Hello",
				"Hello! This is a sample!");
		
		/**
		Modified Code
		**/
		MessageDialog.openInformation(PlatformUI.getWorkbench()
				.getActiveWorkbenchWindow().getShell(),
				CustomString.getString("DIALOG_TITLE"),
				CustomString.getString("DIALOG_MESSAGE"));

Thus far, the UI globalization is similar to a typical Java application. The next section introduces the characteristics of an RCP application.


Splash screen

The splash screen is an image that appears while the application is loading. It notifies the user that the program is loading and provides application information, such as product name and copyright. Usually the splash screen for an RCP application is named splash.bmp and is under the root folder of the plug-in project. However, splash.bmp is under the root folder only for English. To provide different splash screens according to languages in a multilingual application, you need to follow the splash screen path rules. Figure 3 shows an example.

Name the plug-in project root folder <plugin-root>. splash.bmp. It must be put in <plugin-root>/nl/<Language Code>/<Country Code>. For example, you need to put the splash screen file for Simplified Chinese into <plugin-root>/nl/zh/CN.

Figure 3. Splash screen path rules
Splash screen directory structure

Welcome page

The welcome page feature is provided by the org.eclipse.ui.intro plug-in. You can define specialized pages that introduce products to new users. The welcome pages are shown the first time a product is started and are a way to educate users about a product's functions. The RCP welcome page consists of an introductory content file and page files (HTML, images, CSS, etc.).

Since you might have one set of page files for each language, you need to use different introContent.xml to point to different welcome pages according to locale. The intro content file is referenced by plugin.xml. You abstract the intro content file name in plugin.xml as external strings. The external strings are stored in a properties file with the naming convention plugin_<Language_Code>_<Country_Code>.properties. The relationships between the files is shown in Figure 4.

Figure 4. Relationships between globalized welcome pages
Relationships between globalized welcome pages

The code snippet in Listing 6 is from plugin.xml. The variable %welcome.page is used in the content attribute instead of the hard-coded file name introContent.xml. The real file name is put in a properties file so that plugin.xml can find the corresponding content file according to locale.

Listing 6. Welcome page section of plugin.xml
   <extension
         point="org.eclipse.ui.intro.config">
      <config
            introId="helloworld.intro"
            content="%welcome.page"
            id="HelloWorld.configId">
         <presentation
               home-page-id="root">
            <implementation
                  kind="html"
                  os="win32,linux,macosx">
            </implementation>
         </presentation>
      </config>
   </extension>

Let's use Chinese as an example. When users launch the Hello World application in the Chinese environment, plugin.xml will find the Chinese external string file plugin_zh_CN.properties and will get the file name according to the key name welcome.page in the properties file. The Chinese content file introContent_zh_CN.xml will be used, as shown below.

Listing 7. Intro content file name in plugin_zh_CN.properties
   #Properties file for HelloWorld
Bundle-Name = HelloWorld Plug-in
perspective.name = RCP Perspective
product.name = Hello World
welcome.page=welcome/introContent_zh_CN.xml

You can see how the introContent_zh_CN.xml file points to the Chinese welcome page in HTML format. The welcome_zh_CN.html is an HTML file that has product introduction information in Chinese. People using the application in the Chinese OS will see the Chinese welcome page.

Listing 8. Welcome page set in introContent_zh_CN.xml
<?xml version="1.0" encoding="utf-8" ?>
<introContent>
    <page id="root" content="welcome_zh_CN.html"/>
</introContent>

Plug-in and product

The information in the plug-in and product, such as product name, main window title, and About text, can also be globalized. This information is stored in the plugin.xml. You can use the same globalization approach as with the welcome page. Only plugin.xml and plugin.properties are required for this effort. All information in plugin.xml can be externalize to plugin.properties.

Listing 9. Product information section of plugin.xml
   <extension
         id="product"
         point="org.eclipse.core.runtime.products">
      <product
            application="HelloWorld.application"
            name="%product.name">
         <property
               name="windowImages"
               value="icons/alt_window_16.gif,icons/alt_window_32.gif">
         </property>
         <property
               name="appName"
               value="%product.name">
         </property>
         <property
               name="aboutText"
               value="%about.text">
         </property>
      </product>
   </extension>

Using the previous plugin.properties file, you add two more properties: product.name and about.text. The value of product.name is shown on the window title and about menu. The value of about.text is shown when you open the About dialog.

Listing 10. plugin.properties
#Properties file for HelloWorld
Bundle-Name = HelloWorld Plug-in
perspective.name = RCP Perspective
welcome.page=welcome/introContent.xml
product.name = Hello World
#About text has multiple line.
about.text=This is HelloWorld\n\
\n\
Version 1.0

If the properties file contains non-ASCII characters, such as the product name or about text, you need to convert the file from native encodings to ASCII with escaped Unicode. <JDK_HOME>\bin\native2ascii can be used to finish the conversion. For the Chinese resource bundle plugin_zh_CN.properties, you need to do the conversion. After conversion, the plugin_zh_CN.properties looks like Listing 11.

Listing 11. plugin_zh_CN.properties
#Properties file for HelloWorld
Bundle-Name = HelloWorld Plug-in
perspective.name = RCP Perspective
product.name = \u4f60\u597d
welcome.page=welcome/introContent_zh_CN.xml
about.text=\u8fd9\u662f\u4e00\u4e2a\u4f8b\u5b50\n\
\n\
\u7248\u672c 1.0

Standard Eclipse UI elements

Eclipse has some UI elements that are not part of your application, such as the tool-tip maximize and minimize window button. For your application UI, you also need to globalize these UI elements. Fortunately, Eclipse helps to resolve the problem. Download the language pack for Eclipse and put them under the plug-ins directory of your RCP application. The UI elements will be globalized automatically when you launch your application.


Summary

There are many kinds of UI elements in an RCP application. You need to use different approaches to globalize different UI elements. This article introduced the globalization (G11N) implementation of toolbar, menu, dialog, splash screen, welcome page, product information, and standard Eclipse UI elements.

Though the sample Hello World application has very limited functions, it covered most of the UI elements. You can now build a fully globalization-supported UI for your RCP application.


Download

DescriptionNameSize
Hello Worldos-eclipse-globalrcp-HelloWorld.zip161KB

Resources

Learn

Get products and technologies

Discuss

  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source, Java technology
ArticleID=405380
ArticleTitle=Globalize your Eclipse RCP application
publish-date=07072009