Support free tutorials:











vogella training Training Books



Eclipse RCP and Plugin Internationalization - Tutorial

Lars Vogel

Version 2.3

03.09.2013

Revision History
Revision 0.1 16.08.2009 Lars
Vogel
Created
Revision 0.2 - 2.3 10.08.2010 - 03.09.2013 Lars
Vogel
bugfixes and enhancements

Eclipse internationalization and localization

This article describes how to externalize your strings in Eclipse RCP and Eclipse plug-ins and how to support different languages. Includes how to translate your Eclipse 4.x workbench model.

This article is based on Eclipse 4.2 (Eclipse Juno).


Table of Contents

1. Internationalization of Eclipse plug-ins
1.1. Translation of Java applications
1.2. Property files
1.3. Relevant files for translation
1.4. Best practices
1.5. Setting the language in the launch configuration
2. OSGi resource bundles
3. Translating plugin.xml
4. Translating the application model
5. Using translations in source code
5.1. Translating your custom code
5.2. Translating SWT and JFace code
6. Exporting Plug-ins and Products
7. Common problems with i18n
8. Eclipse 4 internationalization
9. Tutorial: Translate plugin.xml
10. Support free vogella tutorials
10.1. Thank you
10.2. Questions and Discussion
11. Links and Literature
11.1. Source Code
11.2. Eclipse i18n resources
11.3. vogella Resources

1. Internationalization of Eclipse plug-ins

1.1. Translation of Java applications

The process of preparing an application for being translated into several languages is called internationalization. This term is typically abbreviated to i18n.

The process of translating the application is called localization and is abbreviated to l10n.

1.2. Property files

Java applications are typically translated via property files. Based on the language of the user, the Java runtime searches for the corresponding resource bundle using language identifiers. If a certain language identifier is not provided, the Java runtime will fall back to the next general resource bundle.

For example:

  • messages.properties: default language file, if nothing else is available

  • messages_de.properties: used for German

  • messages_en.properties: default for English

  • messages_en_US.properties: US English file

  • messages_en_UK.properties: British English file

Resource bundles in Java are always LATIN-1 encoded.

1.3. Relevant files for translation

The following table lists the relevant elements for translation of an Eclipse based application.

Table 1. Translation relevant entities for Eclipse plug-ins

Entity Description
plugin.xml Primarily important for Eclipse 3.x based plug-ins.
application model (Application.e4xmi and fragment files) Describes the application model in Eclipse 4.
Source Code The source code contains text, e.g. for labels which also must be translated.


1.4. Best practices

It is best practice to have one language plug-in which defines the texts for the main language.

Additional languages for Eclipse plug-ins are typically provided via fragments which extend the host plug-in.

1.5. Setting the language in the launch configuration

By default Eclipse uses the language configured in the operating system of the user.

For testing you can set the language manually. In your Eclipse launch configuration on the Arguments tab you can specify the runtime parameter -nl to select the language, e.g. -nl en.

2. OSGi resource bundles

For the translation of the plugin.xml and application model files the Eclipse runtime uses by default OSGi resource bundles. These are based on property files in the OSGI-INF/l10n/ folder. OSGi expects at least one bundle property file in this folder, i.e. bundle.properties.

Via the Bundle-Localization attribute in the MANIFEST.MF file, you point to these files.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: I18n
Bundle-SymbolicName: de.vogella.rcp.i18n; singleton:=true
Bundle-Version: 1.0.0.qualifier
Bundle-Activator: de.vogella.rcp.i18n.Activator
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime
Bundle-ActivationPolicy: lazy
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Bundle-Localization: OSGI-INF/l10n/bundle 

Tip

OSGI-INF/l10n/bundle is also the default value which is used if no value is specified.

The bundle.properties file contains key/values. The key can be used in your application model and the plugin.xml file via %key. At runtime the key is substituted with the corresponding value.

#Properties file
TodoOverviewPart=Overview of Todos
TodoDetailPart=Todo Details 

Alternative languages are defined via additional property files. The filename of these files include a language, country variant, e.g. bundle_en.properties.

3. Translating plugin.xml

The key in your property file can be used in the definition of extensions in the plugin.xml file via the %key reference.

The Eclipse tooling supports extracting existing String values from the plugin.xml file. Select your plugin.xml file, right-click on it and select Plug-in ToolsExternalize Strings.

Eclipse PDE Wizard for externizing plugin.xml

Via PDE ToolsInternationalize you can also directly create one or several fragments for the result of the internationalization.

4. Translating the application model

The translation of model elements is similar to the translation to the plugin.xml file. Use %key for labels in the model as depicted in the following screenshot.

How to use external strings in the workbench model

Currently the application model tooling includes rudimentary support for extracting Strings. Press the right mouse button on an empty space in the application model editor and select Externalize Strings.

Warning

This tooling extracts all Strings from the application model. If you want to replace only a set of relevant Strings you have to do this manually. If you do it manually you can use the PDE wizard as described in Section 3, “Translating plugin.xml” to create the bundle.property file and the OSGi reference.

5. Using translations in source code

5.1. Translating your custom code

It is possible to translate the Java source with two different approaches, based on Strings and based on constants. The approach based on constants is more reliable and should be preferred. To enable this support you need to configure the org.eclipse.core.runtime plug-in as dependency in your related plug-in.

To translate Strings in the source code, select the file you want to translate and select SourceExternalize Strings.

Externizing strings in source files dialog

Please note that the Use Eclipse's string externalization mechanism option is only visible if you have the org.eclipse.core.runtime plug-in configured as a dependency in your plug-in.

In this wizard you can select which Strings should be translated, which can be skipped for the translation and which Strings should be marked as not translatable.

If you select that a String should not be translated, Eclipse will mark the occurrence with a $NON-NLS comment in the source code.

As the result a Messages class is generated which serves as an access point for the properties file.

package test;

import org.eclipse.osgi.util.NLS;

public class Messages extends NLS {
  private static final String BUNDLE_NAME 
    = "test.messages"; //$NON-NLS-1$
  public static String View_0;
  public static String View_1;
  static {
    // initialize resource bundle
    NLS.initializeMessages(BUNDLE_NAME, Messages.class);
  }

  private Messages() {
  }
} 

Via the BUNDLE_NAME constant it points to a resource message*.properties file in the test package. * is a placeholder for your locale, e.g. _de,_en, etc.

View_0=test.view
View_1=Hello 

In your code you access the translations via the Message class.

label.setText(Messages.View_1); 

You can also use placeholder in the messages and evaluate them with the NLS.bind() method.

MyMessage = {0} says {1} 

// NLS bind will call the toString method on obj
NLS.bind(Message.MyMessage, obj, obj); 

If Strings should be consistently used over several plug-ins, it is best practice to create a separate plug-in or fragment for the translations. All plug-ins which want to use the translations define a dependency to the corresponding plug-in.

Additional languages are typically contributed via Eclipse fragment projects to this message plug-in.

5.2. Translating SWT and JFace code

The SWT and JFace plug-ins include their resource translation files. You can change these default texts and their translations because resource bundles have an override support built in.

If you supply a different file of the SWT or JFace translation bundles in a fragment or plug-in (such as SWTMessage_de.properties), then the most local bundle matching the current locale is used.

To change the text supplied by SWT and JFace do the following:

  • Optional create a plug-in (or fragment) which will hold the translations

  • Create the org.eclipse.jface and org.eclipse.swt.internal packages in a selected plug-in or fragment

  • Copy the org/eclipse/jface/message.properties file from the org.eclipse.jface plug-in and the org/eclipse/swt/internal/SWTMessage.properties file from the SWT plug-in to the corresponding packages in your project

  • Provide the files with your desired language extensions, e.g. message_de.properties

  • Edit the files to contain your text properties

6. Exporting Plug-ins and Products

The build.properties file in a plug-in defines which of the files are included in the exported product.

You must include your property files in the build.properties file, otherwise your translations will be missing in the exported product.

7. Common problems with i18n

  • Translations not available in the exported product: Check the build.properties file of the plug-in which provides the property files, if the property files are included in the export.

  • Translations are not displayed in the application: OSGi caches text information, select Clear Configuration in your launch configuration.

8. Eclipse 4 internationalization

Eclipse 4 introduced a translation service via the TranslationService interface. The default implementation of this class is the BundleTranslationProvider which will work on property files, but you can provide your own OSGi service which uses a different source, e.g. a database to get the translations.

This service is stored in the application context. You can replace it there, e.g. via a life cycle hook. By storing it in the IEclipseContext you can have different translation services for different local contexts, e.g. for different windows you can use different translation services.

An alternative implementation is provided by the e4 tools project. The usage of this service is described in the following blog entry: Using the new message extension by Dirk Fauth and Tom Schindl.

Tip

See also the links section at the end of this book to see the link to the full blog series on this topic.

9. Tutorial: Translate plugin.xml

Create a new Eclipse RCP application "de.vogella.rcp.i18n" based on the "RCP application with a view" template. Check the contributions to the "org.eclipse.ui.views" extension point in your plugin.xml file and validate that the name of the View is hard coded to "View".

Right-click on the plugin.xml file and select PDE ToolsExternalize Strings. Accept the default and press ok.

This will create the file bundle.properties and replace the hard-coded string in plugin.xml with a "%key" placeholder, e.g. %View.

<extension
       point="org.eclipse.ui.views">
    <view
         name="%View"
         class="de.vogella.rcp.i18n.View"
         id="de.vogella.rcp.i18n.view">
    </view>
</extension> 

Copy bundle.properties to "bundle_fr.properties" and "bundle_en.properties" Change the text in the property views for the view.

Start you application in the different languages and valid that the translation is correctly used.


View = Lars Test
 

10. Support free vogella tutorials

Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.

10.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

10.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

11. Links and Literature

11.1. Source Code

Source Code of Examples

11.3. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system