About the i18n Library

This library provides a single class - I18nUtil - which provides a wrapper over the standard Java ResourceBundle and MessageFormat classes.

The i18n library, like all x1seven Elements components, is provided under the Lesser GNU Public License version 2.1.

About x1seven Elements

The x1seven Elements projekt provides small focused components that make it easier to build enterprise applications.

All of the components in the x1seven Elements projekt are open-source under the LGPL version 2.1. This license allows x1seven Elements components to legally be used and distributed in other open-source and commercial projekts.

Accessing I18nUtil

The useage pattern for this is similar to Log4J: each class that requires internationalization services creates a private static instance initialized for the appropriate resource bundle (by it's base name);

public MyClass extends Object {

  // Get an Apache Log4J Logger
  private static final Logger LOGGER =
    Logger.getLogger(MyClass.class);

  // Get a x1seven Elements I18nUtil
  private static final I18nUtil I18N =
    new I18nUtil("com.x1seven.myapp.Resources");

  ...

}

This causes I18nUtil to look for a resource bundle in the com.x1seven.myapp package called Resources.

I18nUtil provides a few other construction options, including by package + base name, and by class.

// Gets a I18nUtil instance for the resource
// bundle in the same package and with the same
// name as the supplied class.
public I18nUtil(Class clazz);

// Gets a I18nUtil instance for the resource
// bundle with the supplied name in the
// supplied package
public I18nUtil(Package pkg,
  String resourceBundleName);

Another common constructor to use is:

public I18nUtil(Class clazz,
  String resourceBundleName);

This provides a convenient way to grab a resource bundle from the same package as the class you want to use it from. For example, say we wanted to grab an I18nUtil instance for a resource bundle called "Resources" from within a class called "Main":

private static final I18nUtil m_i18n =
new I18nUtil(Main.class, "Resources");

This is the constructor to use if you want to have per-package resource bundles.

Note that the underlying ResourceBundle class has the option of caching ResourceBundle instances, so I18nUtil does not attempt to implement it's own caching strategy. See ResourceBundle for more information.

Getting Internationalized Resources

Once you've setup your I18nUtil instance, you can use it to get internationalized resources from the underlying bundle using the getString methods. This method is overloaded, providing signatures for doing various permutations of value substitution.

The full set of getString method signatures is as follows:

public String getString(
  String key);
public String getString(
  String key, Object arg0);
public String getString(
  String key, Object arg0, Object arg1);
public String getString(
  String key, Object arg0, Object arg1,
  Object arg2);
public String getString(
  String key, Object arg0, Object arg1,
  Object arg2, Object arg3);
public String getString(
  String key, Object arg0, Object arg1,
  Object arg2, Object arg3, Object arg4);
public String getString(
  String key, Object args[]);

For example, say our resource bundle contained the resource:

the.weight.is.invalid.weight.must.be.between=
  The weight {0} is invalid.  Weight must be
  between {1} and {2}.

The following code shows how we could use I18nUtil to get the message:

String message = m_i18n.getString(
    MESSAGE_INVALID_WEIGHT,
    new Double(weight),
    new Double(minWeight),
    new Double(maxWeight));

In this example code, the MESSAGE_INVALID_WEIGHT constant would be defined somewhere to hold the key into the resource bundle. Note that Java's MessageFormat class requires Objects, so where we want to substitute values from primitives, we need to wrap them in the equivalent java.lang Object.