Template Localization

From portlet-skeleton (inactive) Wiki
Jump to: navigation, search

Contents

Overview

The localization has been changed in version 0.3 since extensive code duplication in previous versions is very bad practice and results in maintainance resp. synchronization problems.

Therefore the directory path structure was changed so that the locale part was omitted. That means using one template for all languages.

There is a new class org.evolvis.portletskeleton.utils.LocaleUtil which is always set in the velocity context. It is accessible via the variable $tr (as in translation).

The LocaleUtil's language is determined from the current portlet request's getLocale() method. This means that the browser's language request, the portal language and the portlet's supported languages is taken into account for determining the locale.

Important notice: The default language in Java VM should be set to fallback language of the templates (using VM argument -Duser.language=<lang> for example).

Translation files

The translation mechanism used is the ordinary Java resource bundle mechanism.

It is recommended to set a locale resource path for the servlet's init params in the web.xml:

<web-app>
   ...
   <servlet>
     ...
     <servlet-class>org.evolvis.portletskeleton.VelocityServlet</servlet-class>
     ...
     <init-param>
       <param-name>org.evolvis.portletskeleton.VelocityServlet.resource.path</param-name>
       <param-value>/translations</param-value>
     </init-param>
     ...
   </servlet>
   ...
 </webapp>

With this example you will put your translation files under the resources directory (for the classloader) into the translations directory.

Example

Suppose you want to use translation for MyPortlet extends VelocityPortlet.

In the portlet.xml use specify:

<supported-locale>en</supported-locale>
<supported-locale>de</supported-locale>

The path for the velocity VIEW template is now WEB-INF/velocity/myportlet/view.vm (not using a theme).

The fallback locale path for this template is translations/myportlet/view.properties. The fallback language will (most likely) be English (note setting Java default language as above).

The german translation path is translations/myportlet/view_de.properties.

As you can see, the ordinary Java resource bundle technique is used for auto-detecting the files.

Special regards

Searching in bundles

In the velocity template you can use $tr.get("My key") to use the translations.

The resource bundles are then searched in the Java resource bundle way for the key My_key.

Note: Whitespace in keys is replaced by underscores while searching in resource bundles!

If a key is not found in any bundle or if no appropriate bundle was found, then the original key is returned.

Note: The original key is returned, not the whitespace-purged key!

Formatting

Formatting is also supported by LocaleUtil.

The format(key, List) method is looking for the key in a bundle and the using Java's MessageFormat formatting. To pass arguments in the velocity template you should use $tr.format("key1", [ $object1, "String2" ]).

Using lists is standard procedure in velocity but vararg format method is also present in the LocaleUtil.

If you want to specify a format directly without using keys in resource bundles, use the formatPattern method.

Another method for convenience is the formatArgs method. This uses the first item of the list as the key(!) and behaves exactly like the format method. It is commonly used if you pass a list with determined key and arguments to the template.