Localized strings appear in *.properties files either within the plugin itself or within attached fragment plugins. These .properties files may be named anything you want. They are are in java.lang.Properties format, that is, key=value format (the same as velocity template property files). Here is what they look like:

# I'm a line comment
EpValidatorFactory_valueRequired=This value is required
!I'm another line comment
EpValidatorFactory_integer=The line can also span multiple\
 lines as long as you escape the newline character

# Spaces between = doesn't matter
EpValidatorFactory_positiveInteger = To display a \\ you need to escape it as well

There must be a *.properties file for each language within the plugin/fragment. These files are named <filename><language><country>.properties where <language> and <country> represent the two-letter codes (ISO 639 and ISO 3166) used to signify the language and country. Country and language don't need to be specified, see Default Language below.

Within java code, localized strings can't be looked up automatically, they must be retrieved manually. All Commerce Manager plugins define a class that allows that plugin to retrieve localized strings from a properties file. An short example of the class used is as follows:

public class CoreMessages {
    private static final String BUNDLE_NAME =
        "com.elasticpath.cmclient.core.CorePluginResources"; //$NON-NLS-1$

    private CoreMessages() { super(); }

    public static String EpLoginDialog_LoginButton;
    public static String ...
    ...

    static {
        NLS.initializeMessages(BUNDLE_NAME, CoreMessages.class);
    }
}

The static block takes care of all the initialization. It is important that all the localized string in the class are static public strings and not final. It is also important that the names of these static strings occur exactly as they are in the properties file (which means no periods and case sensitive) otherwise initializeMessages() won't be able to initialize that string. All that is required now is to call the appropriate static strings from the class directly.

Other than the keys, one thing must change in order to use this class elsewhere: BUNDLE_NAME. This variable specifies both the package and file name of the properties file to use when initializing the messages. The filename must not include .properties as this is automatically appended. If this file doesn't exist, no exceptions are thrown, you'll just receive "NLS missing message: <key> in: <BUNDLE_NAME>" from the string where your localization is suppose to be.

What if there is some sort of variable in the string? Call the bind() method to do this:

String myMessage = NLS.bind(
    CoreMessages.TemplateMessage,
    "one binding"); //$NON-NLS-1$
myMessage = NLS.bind(
    CoreMessages.TemplateMessage,
    "two bindings", //$NON-NLS-1$
    "for the second"); //$NON-NLS-1$
myMessage = NLS.bind(CoreMessages.TemplateMessage, new Object[] {
    new Object(),
    "more than two objects", //$NON-NLS-1$
    null,
    new Integer(5) });

In this context, it's not at all that interesting. What's important here is that we can insert an arbitrary number of variables into a message. Message reference these variables by inserting {0} for argument 0, {1} for argument 1, and so on. On a side note, if you give a null reference as the object array or not enough arguments in the object array, the string returned will have one or more <missing key> strings within it (no thrown exceptions!). Object arrays that have more objects than there is arguments in the template string will not be used. An important note about this method is that you can give an object to the bind() method, it will just use the toString() method to represent it as a string.

Files that are not within classes could also require string localization. These string are all put into another properties file, which has the same format as other properties files. The name is plugin.properties by convention but could be named otherwise. To specify that a plugin should use plugin.properties, Bundle-Localization: plugin should be inserted into the plugins MANIFEST.MF file. This is only required in the host plugin with respect to fragments. Bundle-Localization specifies a path to a file, relative to the root of the plugin, where the properties file is stored. The file name must not include .properties because this is automatically appended.

Localization can happen almost anywhere, including within MANIFEST.MF and plugin.xml. Both of these use plugin.properties to store their string localizations.

There exists a special file called about.mappings (required name) that can be used here as well. This file is useful for storing global strings common to all lanugages (i.e. a version number). It is important to note though that mappings in this file are only used within the about text (Help->About...) which isn't really useful, but helpful to know. The file has the same format as *.properties files except that keys must be non-negative integers.

Think of a fragment as a half-plugin. It's not quite big enough to be a whole plugin, but big enough to be modularized. Things that are stored in here are generally aren't required for the host plugin (i.e. OS specific bindings for SWT) or localization files. Fragments reference plugins which means that a fragment can reference only 1 plugin and not multiple.

• File Naming
  • The messages class should be named <pluginName>Messages
  • Properties files should be named <pluginName>PluginResources
  • In the case of multiple messages classes, <pluginName> should be replaced with something meaningful
  • Fragments are named the same as the referencing plugin with appened .nl1 (or .nl2 for second localization pack)
• Localization of plugin.xml and MANIFEST.MF** Plugins localization entries should live within plugin.properties*** Requires Bundle-Localization: plugin within MANIFEST.MFof the plugin
  • Fragment localization entries should be separate and therefore live within nl_fragment.properties*** Requires Bundle-Localization: nl_fragment within MANIFEST.MFof the fragment
    • nl_fragment.properties only needs to be included in the fragment and not the plugin
  • about.mappings should live within the plugin (if required by a plugin)
• Location
  • Each plugin will have it's own specialized messages class located in the root package (i.e. src/main/com/elasticpath/cmclient/core/CoreMessages.java)
  • The properties file for this messages class will live in the same location
  • There should be only one messages class, although some extenuating circumstances might require more than one
• Properties files
  • All comments should use # instead of !
• Property Keys
  • Keys should generally follow the convention <contributionName><contributionType>_<something> (i.e. productEditor_skuCode)
    • Note: Most classes follow the <contributionName><contributionType> naming convention
  • Reusable keys should try not to follow the above convention
• Strings
  • Every string in classes must either be externalized or have //$NON-NLS-x$comments
    • Multiple strings on the same line are specified by //$NON-NLS-1$ //$NON-NLS-2$ for the first and second string on the line
• Default Language
  • Default lanugage files (.properties) will live in their respective directories within the *plugin not the fragment
  • All other language files will live inside a fragment