Search  

How i18n works in Yanel

Overview

I18n serves for translating parts of your application to different languages. It uses a message catalogue to look up a message in a given language which is identified by a unique key.

Example

This example assumes that you are using the XMLResource (or any other subclass of BasicXMLResource).

Example message catalogue (let's say it's stored in the default repository of your realm, with the path /i18n/foo.xml):

<?xml version="1.0" encoding="UTF-8" ?>
<messages>
  <message key="foo.user">
    <text language="de">Benutzer</text>
    <text language="en">User</text>
  </message>
  <message key="foo.logout">
    <text language="de">Abmelden</text>
    <text language="en">Log out</text>
  </message>
  <message key="foo.registeredUsers">
    <text language="de">Es sind {0} Benutzer registriert.</text>
    <text language="en">{0} users are registered.</text>
  </message>
</messages>

To translate text using this catalogue, use the following code in your xslt:

<i18n:text xmlns:i18n="http://www.wyona.org/yanel/i18n/1.0" key="foo.user"/>

To translate an attribute:

<input type="submit" value="foo.logout" i18n:attr="value"/>

Or when there are multiple attributes using i18n:

<input type="button" name="Name" value="foo.button.value" title="foo.button.tooltip" i18n:attr="value title"/>

 

To translate a text with parameters:

<i18n:translate>
  <i18n:text key="foo.registeredUsers"/>
  <i18n:param>7</i18n:param>
</i18n:translate>

The catalogue has to be associated with the content. There are two ways to do so:

1. Resource-specific messages
   Add a property to the resource configuration file (.yanel-rc):

   <i18n-catalogue>yanelrepo:/i18n/foo.xml</i18n-catalogue>

2. Realm specific messages
   Add the following element to your realm.xml:

   <i18n-catalogue>yanelrepo:/i18n/foo.xml</i18n-catalogue>

How it works

There is a transformer (I18nTransformer) which transforms the <i18n:text> elements into the text messages from the catalogue. If no message is found for a given key and a given language, fallback to the default language is applied. If still no message is found, the transformer inserts the message key.

As of today there are three different versions of this transformer in yanel: I18nTransformer, I18nTransformer2, and I18nTransformer3. The first two versions are deprecated. They use a different syntax and they support only plain-text property files as catalogues (ResourceBundles, which means the catalogues are loaded from the classpath).
I18nTransformer3 still supports the old syntax and also allows to use ResourceBundle catalogues, so it's the recommended choice.

Multiple Catalogues

It is possible to have more than one catalogue.
A resource configuration can have several catalogues, the realm can have one, and Yanel has a global message catalogue (see WEB-INF/classes/global_en.properties or WEB-INF/classes/global_de.properties). Yanel will look for a message with a given key first in the resource catalogues, then in the realm catalogue, and eventually in the global catalogue.

Catalogues of a resource

One can also configure a resource specific catalogue. See for example:

src/realms/yanel-website/res-configs-repo/data/en/contact.html.yanel-rc

and in particular

<yanel:property name="i18n-catalogue" value="contact-form"/>

which is the resource configuration of http://127.0.0.1:8080/yanel/yanel-website/en/contact.html.

The i18n properties files of the contact resource are located inside the directory src/resources/contact-form/conf, which are copied during the build process to local/TOMCAT/webapps/yanel/WEB-INF/classes, from where the I18nTransformers will read them.

---