Locale specific files

Fragments are a convenient way to package national language translations. Let's look more closely at the directory structure used for installing locale-specific translation files. This directory structure is used regardless of whether the translated files are packaged in a fragment or delivered in the original plug-in.

There are three mechanisms for locating locale specific files in a plug-in.

Platform core mechanism (the platform's runtime locale-specific sub-directory search)
Java resource bundles (java.util.ResourceBundle)
The plugin.properties mechanism (Translating values from the plugin.xml files)

It is important to understand which mechanism is used to access any given file that must be translated so that you'll know what to name the file and where to put it in the file system relative to the plug-in.

Platform core mechanism

The platform core defines a directory structure that uses locale-specific subdirectories for files that differ by locale. Translated files are placed in a directory called nl under the plug-in. For example, the following install tree shows a trivial (no code) plug-in with locale-specific translations of its about.properties file. The various translations are shown as coming from a plug-in fragment rather than the plug-in itself. This is typical for shipping translations separately from the base, but you could also place the nl sub-directory under the plug-in itself.

acmeweb/
  eclipse/
    plugins/
      com.example.acme.acmewebsupport_1.0.0/
        plugin.xml
        about.properties    (default locale)
      com.example.acme.fragmentofacmewebsupport_1.0.0/
        fragment.xml   (a fragment of com.example.acme.acmewebsupport 1.0.0)
        nl/
          fr/
            about.properties  (French locale)
            CA/
              about.properties  (French Canadian locale)
            FR/
              EURO/
                about.properties (French France Euros)
          en/
            about.properties  (English locale)
            CA/
              about.properties  (English Canadian locale)
            US/
              about.properties (English US locale)
         de/
            about.properties (German locale)

The files to be translated are not contained in JAR files. Each file should have exactly the same file name, but be located in subdirectories underneath the nl sub-directory in the fragment's (or plug-in's) root.

Only the most specific file is accessed at runtime. The file paths are searched as part of the Platform.find, IPluginDescriptor.find and Plugin.find mechanism. For example, suppose the default locale is en_CA, and a plug-in searches for the about.properties as follows:

somePlugin.find("$nl$/about.properties");

The method will return a URL corresponding to the first place about.properties is found according to the following order:

com.example.acme.acmewebsupport_1.0.0/nl/en/CA/about.properties
com.example.acme.fragmentofacmewebsupport_1.0.0/nl/en/CA/about.properties
 ...  		<any other fragments>
com.example.acme.acmewebsupport_1.0.0/nl/en/about.properties
com.example.acme.fragmentofacmewebsupport_1.0.0/nl/en/about.properties
 ...
com.example.acme.acmewebsupport_1.0.0/about.properties
com.example.acme.fragmentofacmewebsupport_1.0.0/about.properties

This mechanism is used by plug-ins to search for well known file names inside other plug-ins. This includes the following well known file names:

preferences.properties (externalized strings for plug-in -specific preference default overrides)
about.properties (externalized strings for feature "about" information)
plugin_customization.properties (externalized strings for product-specific preference default overrides)
splash.bmp (product-specific splash screens)

(Note: The plugin.properties and fragment.properties are conspicuously absent from this list. They are treated in a sightly different way described below.)

Java resource bundles

The standard Java handling of property resource bundles is used for other files. Translated files are contained in a JAR file, with each properties file having a locale-specific name, such as "message_en_CA.properties". The files are in package-specific subdirectories and may appear in the plug-in itself or one of its fragments. Each translated properties file may be partial since lookup of keys accesses a well-defined chain of properties files.

The plugin.properties mechanism

The mechanism used to translate plugin.properties files uses the Java resource bundles naming convention. However the files must be located in the root of the plug-in or in the root of a fragment of this plug-in. The same rules apply to the translation of MANIFEST.MF.

Defining NL fragments

The shape of NL fragments has evolved slightly since 2.1. Previously all translation files (including the plugin.properties) were provided in a jar. This was inconsistent since the plugin.properties file was provided at the root of the plug-in.
To adapt your NL fragment to the new model, remove the plugin.properties translation files from the jar and put them at the root of the fragment as siblings of fragment.xml. For example, the new shape of the NL fragment for org.eclipse.ui.workbench is the following:

  org.eclipse.ui.workbench.nl/
     fragment.xml
     plugin_fr.properties
     plugin_pt_BR.properties
     ...
     nl1.jar