Internationalization Configuration

Internationalization Configuration

1 Overview

All aspects of internationalization in eXo products are covered. You should have a general knowledge of Internationalization in Java products. Sun created a good internationalization tutorial.

2 Introduction

A typical locale file can be found in:
.../WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties

You should notice that

• the file is located in the classes folder of your WEB-INF, this way they are loaded by the ClassLoader.
• all resource files are in the subfolder locale.
• resources for the navigation? are located in a navigation subfolder of locale.
• resources concerning the navigation of a group are in a navigation/group subfolder. The other possible navigations are user and portal.

The executive-board_en.properties resource file contains:

organization.title=Organization
organization.newstaff=New Staff
organization.management=Management

3 LocalesConfig

In .../WEB-INF/conf/common/common-configuration.xml you find:

<component>
  <key>org.exoplatform.services.resources.LocaleConfigService</key> 
  <type>org.exoplatform.services.resources.impl.LocaleConfigServiceImpl</type> 
 <init-params>
 <value-param>
  <name>locale.config.file</name> 
  <value>war:/conf/common/locales-config.xml</value> 
  </value-param>
  </init-params>
  </component>

The configuration points to the locale configuration file like this one: .../WEB-INF/conf/common/locales-config.xml

<locale-config>
 <locale>ar</locale>
 <output-encoding>UTF-8</output-encoding>
 <input-encoding>UTF-8</input-encoding>
 <description>Default configuration for the Arabic locale</description>
 <orientation>rt</orientation>
</locale-config>

The locale has to be defined using ISO 639, in this example "ar" is Arabic.

This configuration defines also the list of languages in the "Change Language" section of the portal.

3.1 Encoding

It's highly recommended to always use UTF-8. You should also encode all property files in UTF-8.

In the java implementation, the encoding parameters will be used for the request response stream. The input-encoding parameter will be used for request setCharacterEncoding(..).

3.2 Orientation

The default orientation of text and images is Left-To-Right. As you know eXo support Right-To-Left orientation. Therefore for Arabic you define <orientation>rt</orientation>

4 ResourceBundleService

The resource bundle service is configured here: // http://fisheye.exoplatform.org/browse/projects/portal/trunk/web/portal/src/main/webapp/WEB-INF/conf/common/common-configuration.xml?r=28705

Caution: Other eXo products like DMS use dedicated configuration file called "resource-bundle-configuration.xml".

A typical configuration looks like this one:

<component>
    <key>org.exoplatform.services.resources.ResourceBundleService</key>
    <type>org.exoplatform.services.resources.jcr.ResourceBundleServiceImpl</type>
    <init-params>

      <values-param>
        <name>classpath.resources</name>
        <description>The resources that start with the following package name should
                     be loaded from file system</description>
        <value>locale.portlet</value>      
      </values-param>      

      <values-param>
        <name>init.resources</name>
        <description>Store the following resources in the DB for the first launch </description>
        <value>locale.portal.expression</value>
        <value>locale.portal.services</value>
        <value>locale.portal.webui</value>
        <value>locale.portal.custom</value>

        <value>locale.navigation.portal.classic</value>
        <value>locale.navigation.group.platform.administrators</value>
        <value>locale.navigation.group.platform.users</value>
        <value>locale.navigation.group.platform.guests</value>
        <value>locale.navigation.group.organization.management.executive-board</value>               
      </values-param>      

      <values-param>
        <name>portal.resource.names</name>
        <description>The properties files of the portal, these files will be merged 
          into one ResoruceBundle properties </description>
        <value>locale.portal.expression</value>
        <value>locale.portal.services</value>
        <value>locale.portal.webui</value>
        <value>locale.portal.custom</value>        
      </values-param>      

    </init-params>
  </component>

There are three parameters: classpath.resources, init.resources, and portal.resource.names. We will talk later about classpath.resources.

In init.resources you have to define all resources that you want use in the product, independently of the fact that they belong to the portal or to the navigation. All these resources are stored in JCR at the first launch of your product. After that, you only can modify these resources using the Internationalization Portlet.

4.1 Portal Resource Bundle

The parameter portal.resource.names defines all resources that belong to the Portal Resource Bundle. This means that these resources are merged to a single resource bundle which is accessible from anywhere in eXo products. As mentioned, all these keys are located in the same bundle, which is separated from the navigation resource bundles.

4.2 Navigation Resource Bundles

There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal. In the example above you see bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles lives in a different sphere, they are independent of each other and they do not belong to the portal.resource.names parameter (because they are not mentioned in portal.resource.names).

As you learned in the introduction you must put the properties for a group in the WEB-INF/classes/locale/navigation/group/ folder.

Example:
.../portal/trunk/web/portal/src/main/webapp/WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties
The folder and file names must correspond to the group hierarchy. The group name "executive-board" is followed by the iso 639 code. For each language you defined in the LocalesConfig you must provide a resource file.

If you ever change the name of a group you also need to change the name of the folder and/or files of the correspondent navigation resource bundles.

You already know the content of executive-board_en.properties:

organization.title=Organization
organization.newstaff=New Staff
organization.management=Management

This resource bundle is only accessible for the navigation of the organization.management.executive-board group.

5 Portlet

5.1 classpath.resources

Portlets are independent application and they deliver their own resource files. You can find an example for the GadgetPortlet:
.../WEB-INF/classes/locale/portlet/gadget/GadgetPortlet_en.properties

All portlet resources are located in the locale/portlet subfolder. The ResourceBundleService parameter classpath.resources defines exactly this subfolder. Doing so the resource file that are in locale/portlet will never be stored in the JCR and reloaded at each start of the application server.

<values-param>
  <name>classpath.resources</name>
  <description>The resources that start with the following package name should
               be loaded from file system</description>
  <value>locale.portlet</value>      
</values-param>

5.2 Example

Let's suppose you want to add a Spanish translation to the GadgetPortlet.

Create the file in:
.../WEB-INF/classes/locale/portlet/gadget/GadgetPortlet_es.properties

In portlet.xml, add Spanish as a supported-locale, the resource-bundle is already declared and is the same for all languages :

<supported-locale>en</supported-locale>
<supported-locale>es</supported-locale>
<resource-bundle>locale.portlet.gadget.GadgetPortlet</resource-bundle>

Find more details about portlet internationalization.

5.3 Standard Portlet Resource Keys

There are three standard keys defined : Title, Short Title and Keywords. Keywords contain a comma-separated list of keywords.

javax.portlet.title=Breadcrumbs Portlet
 javax.portlet.short-title=Breadcrumbs
 javax.portlet.keywords=Breadcrumbs, Breadcrumb

6 Access

Whenever you want to display a property in the user language you use its key. Using the below access method the translation is returned in the preferred language of the current http session:

Groovy Template

String translatedString = _ctx.appRes(key);

Java

WebuiRequestContext context = WebuiRequestContext.getCurrentInstance() ;
ResourceBundle res = context.getApplicationResourceBundle() ;
String translatedString = res.getString(key);

7 Debugging resource bundle usage

When an application needs to be translated, it is never obvious to find out the right key for a given translated property. Since the Exo Portal 2.6 when the portal is executed in debug mode it is possible to select among the available languages a special language called Magic locale.

This feature translates a key to the same key value. For instance, the translated value for the key "organization.title" is simply the value "organization.title". Selecting that language allows to use the portal and its applications with all the keys visible and it is easy to find out the correct key for a given label in the portal page.