Internationalization

Calyxo supports i18n from the ground up. At the very basic, Calyxo provides ways to resolve resources in a locale dependent manner. A resource is identified by a bundle name and a resource key.

A resource may be a template, that expects arguments to be expanded to a message.

I18n Support

The de.odysseus.calyxo.base.I18nSupport class contains the methods to lookup resources and to format messages. It is also responsible to serve the desired locale. There's one instance per module. You can get the I18nSupport instance for the current module by invoking one of the various static getInstance() methods.

The getLocale(HttpServletRequest request) method queries for the desired locale. Throughout your application, you should always use this method to determine the desired locale. Applications may call setLocale(HttpServletRequest request, Locale locale) to save the specified locale as the desired locale, usually into session scope.

The getResource(Locale locale, String bundle, String key) method is used to lookup a simple localized resource.

The getMessage(Locale locale, String bundle, String key, Object[] args) message is used to lookup a message resource (with any number of message arguments).

Bundle names may be mapped to another name with the setBundleAlias(String alias, String bundle) method. Subsequent calls to getResource(...) and getMessage(...) with bundle alias will actually result in lookups for bundle bundle. This is useful to keep your logical bundle names (aliases) independent of implementation issues (like Java resource bundle names and locations). Since this is a common module configuration issue, we give the following configuration snippet as an equivalent to I18nSupport.getInstance(moduleContext).setBundleAlias(alias, bundle):

<use>
  <member class="de.odysseus.calyxo.base.I18nSupport">
    <method name="getInstance">
      <arg value="${moduleContext}"/>
    </method>
  </member>
  <method name="setBundleAlias">
    <arg value="alias"/>
    <arg value="bundle"/>
  </method>
</use>

Default I18n Support

The default implementation of I18nSupport used by a module depends on the module's environment:

  • With Calyxo Control, the default mechanism for resources is to use Java's ResourceBundle class. Messages are expanded using Java's MessageFormat class.
    Note
    However, your application may provide its own or customized mechanism. Simply subclass I18nSupport and implement the abstract lookupResource(...) and lookupMessage(...) methods. Refer to the section on Module Initialization on how to make the module use your customized i18n implementation.
  • The Calyxo Base Struts plugin provides a I18nSupport implementation, which wraps and delegates to Struts' MessageResources mechanism. Here, customization is done on the Struts side.

I18n Accessors

The base.i18n.* accessors provided by Calyxo Base make localizing content very easy, for example

${calyxo.base.i18n.locale}
${calyxo.base.i18n.bundle['strings'].resource['user_id']}
${calyxo.base.i18n.bundle['strings'].message['required']['user_id']}

As you can see, there's no need for custom tag libraries to localize your content.