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
Platform core mechanism (the platform's runtime locale-specific
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.
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
about.properties (default locale)
fragment.xml (a fragment of com.example.acme.acmewebsupport 1.0.0)
about.properties (French locale)
about.properties (French Canadian locale)
about.properties (French France Euros)
about.properties (English locale)
about.properties (English Canadian locale)
about.properties (English US locale)
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
mechanism. For example, suppose the default locale is en_CA,
and a plug-in searches for the about.properties as follows:
The method will return a URL corresponding to the first place about.properties is found according to the following
... <any other fragments>
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
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: