Package org.modeshape.common.i18n

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

See:
          Description


Interface Summary
LocalizationRepository A repository of localized property files used by the internationalization framework.
 

Class Summary
ClasspathLocalizationRepository Implementation of a LocalizationRepository 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.
 

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:

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.

However, it is possible to access the localization bundles from other sources using the LocalizationRepository interface that defines a single method for obtaining the URL for a given bundle name and Locale. The resulting URL must be capable of accessing the bundle contents via the URL.openStream() method.

To specify that your localization repository should be used, simply call the I18n#setLocalizationRepository(LocalizationRepository) method once within your application.

Testing the localizations

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

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);
    }
 }
 



Copyright © 2008-2010 JBoss, a division of Red Hat. All Rights Reserved.