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.

Back to top

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.

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.

Back to top

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.

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.

			
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.

			
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.

			
	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.

Back to top

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.

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.

		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"));
			

Back to top

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.

Back to top

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.

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.

   <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.

   #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.

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

Back to top

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.

   <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.

#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.

#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

Back to top

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.

Back to top

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.

Back to top

Download

Information about download methods

Resources

Learn

• Get more details about Eclipse RCP, the minimal set of plug-ins needed to build a rich client application.
  
  
• Take an Eclipse RCP tutorial that covers: creating a first RCP application; working with commands, views, editors, dialogs, usage of preferences and preferences pages; usage of external JARs; creating a product and branding; and adding help to an RCP application.
  
  
• Learn more about Codes for the Representation of Names of Languages (ISO 639.2) and the country names and code elements (ISO 3166-1 and the corresponding ISO 3166-1-alpha-2 code elements).
  
  
• Globalize your On Demand Business discusses how IBM is focusing on competing in an international marketplace.
  
  
• Check out the "Recommended Eclipse reading list."
  
  
• Browse all the Eclipse content on developerWorks.
  
  
• Follow developerWorks on Twitter.
  
  
• New to Eclipse? Read the developerWorks article "Get started with the Eclipse Platform" to learn its origin and architecture, and how to extend Eclipse with plug-ins.
  
  
• Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
  
  
• To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts.
  
  
• Stay current with developerWorks' Technical events and webcasts.
  
  
• Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
  
  
• Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  

Get products and technologies

• Check out the latest Eclipse technology downloads at IBM alphaWorks.
  
  
• Download Eclipse Platform and other projects from the Eclipse Foundation.
  
  
• Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  

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.
  
  

About the authors

Wei 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 is a developer on ECM Widgets. He has more than five years of experience in Eclipse development.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Sample application
• Common resource bundle
• Toolbar, menu, and dialog
• Splash screen
• Welcome page
• Plug-in and product
• Standard Eclipse UI elements
• Summary
• Download
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Open source on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers