Package org.modeshape.common.i18n

A simple framework for defining internationalized strings and obtaining the localized forms.

See: Description

Interface Summary

Interface	Description
I18nResource	Interface which should be implemented by any i18n compliant resource.

Class Summary

Class	Description
ClasspathLocalizationRepository	Class that loads a properties file from the classpath of the supplied class loader.
I18n	An internalized string object, which manages the initialization of internationalization (i18n) files, substitution of values within i18n message placeholders, and dynamically reading properties from i18n property files.
TextI18n	A pass-through implementation of I18nResource which uses an underlying text as the real value, ignoring any kind of internationalization.

Package org.modeshape.common.i18n Description

A simple framework for defining internationalized strings and obtaining the localized forms.

The I18n class represents an internationalized string with the ability to obtain the localized message given a Locale or, if not supplied, the default locale.

Using the I18n objects

To use, simply create a class with a public static non-final I18n instance for each of the internationalized strings. The name of the field is used as the message key in the localization files, so use a name that is meaningful within the codebase. The class should also have a static initializer to populate the I18n instances. For example, here is a class that defines three internationalized strings:

 public final class MyAppI18n {

   public static I18n errorImportingContent;
   public static I18n unableToFindSourceWithName;
   public static I18n executorIsShutdown;

   static {
       try {
           I18n.initialize(MyAppI18n.class);
       } catch (final Exception err) {
           System.err.println(err);
       }
   }
 }
 

You can have as many of these classes in your application or library, so you have the flexibility to organize your I18n objects to suit your needs. You could, for example, define one of these classes in each of your applications modules, or you could even define one in each package.

Localization

The localized strings are loaded from property files based upon the name of the locale and the class containing the I18n message objects (the one with the static intializer):

   <package>.<className>_<localeName>.properties
 

For example, here are the names of some localization bundles for the "org.example.MyAppI18n" class:

• "org.example.MyAppI18n.properties_en" is the bundle containing the English strings
• "org.example.MyAppI18n.properties_fr" is the bundle containing the French strings
• "org.example.MyAppI18n.properties" is the bundle used if no locale is specified

Each of these files is a simple properties file, where the property names (the keys) must match the I18n field names, and the property values are the localized message. So, given the "org.example.MyAppI18n" class above, here is an example of a localization bundle:

 errorImportingContent = Error importing {0} content from {1}
 unableToFindSourceWithName = Unable to find a source named "{0}"
 executorIsShutdown = The executor is already shutdown
 

Note that each of the localized messages may contain number parameters that are replaced with actual values supplied to the I18n.text(Object...) or I18n.text(java.util.Locale, Object...) methods.

Localization Repositories

By default, the localization bundles must be found on the classpath. This makes sense for most applications that include their localization bundles with their JARs or make them available on the classpath. You can always specify the classloader to use, however.

Testing the localizations

The framework provides several utility methods to obtain any problems the were found while loading the localized messages.

• I18n.getLocalizationProblemLocales(Class) returns the set of Locale objects for which there were problems;
• I18n.getLocalizationProblems(Class) returns the set of problems found while loading all of the locales;
• I18n.getLocalizationProblems(Class,java.util.Locale) returns the set of problems found while loading the supplied locale

Problems include any missing messages in a localization file, extra messages in a localization file, or inability to access the localization file.

These utility methods can be used in unit tests to ensure that all locale message bundles were loaded successfully. In fact, this framework provides an abstract unit test that does exactly this. To use simply create a concrete subclass with a no-arg constructor that calls the abstract class's constructor with the Class containing the I18n objects:

 public class MyAppI18nTest extends AbstractI18nTest {
    public MyAppI18nTest() {
        super(MyAppI18n.class);
    }
 }