Cocoon i18n

Utiliser les traductions

On utilise la balise <i18n:text> pour insérer une chaîne à traduire. Une chaîne traduite est constituée de :

1. une chaîne, qui sera affichée ;
2. une clé (key), qui identifie de façon unique la chaîne que l'on souhaite affichée ;
3. un catalogue (catalogue), qui indique où l'on va chercher la clé. Si cet attribut n'est pas présent, on cherchera la clé dans le catalogue défini par défaut (cf. <app>/catalogues-i18n.xmap).

Définition d'une traduction

Dans notre catalogue, on ajouter un élément <message> pour chaque chaîne :

<message key="edit.menu.monModule.intro">chaine affiché si tout marche correctement.</message>

En indiquant à chaque fois :

• la clé : key ;
• le contenu de la chaîne à afficher.

L'espace de nom i18n

Dans la feuille XSL générant notre fichier de sortie, on ajoutera au moins le espace de nom (xmlns) pour l'i18n :

<xsl:stylesheet version="2.0"
  xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
  exclude-result-prefixes="i18n">

Affichage : <i18n:text>

Puis on insérera notre chaîne de la façon suivante :

<i18n:text catalogue="module-monModule" key="edit.menu.monModule.intro">
  chaîne affichée si le catalogue ou la clé pose problème.
</i18n:text>

En précisant bien :

• la clé : key ;
• le catalogue : catalogue, si ce n'est pas celui par défault ;
• un contenu de secours si la traduction souhaitée manque.

Contenu dynamique avec <i18n:translate>

Cocoon permet l'utilisation de placeholder pouvant être dynamiquement substituer par des variables. Ceci est possible avec l'élément <i18n:translate>.

Il faudra appeler la chaîne dynamique de la façon suivante

<i18n:translate>
	<i18n:text catalogue="monCatalogue" key="maCleI18n" >monFallback</i18n:text>
	<i18n:param><xsl:value-of select="$monParametre"/></i18n:param>
</i18n:translate>

Et définir son contenu avec indiquant le numéro du paramètre en crochets {#} comme suit :

<message key="maCleI18n">blabla bla <span class="maClass"> ({0})</span></message>

Important :

La substitution ne marche pas quand le placeholder est dans un attribut<ref>ParamSaxBuffer doesn't substitute params within attribute values</ref>.

<message key="maCleI18n">blabla bla <href="{0}/wrong.html" > ({0})</span></message>

On se retrouvera donc avec {#} dans le document final et non la chaîne attendue.

Ajouter un catalogue

Catalogue des traductions

On commence par créer un nouveau fichier aussi appelé catalogue, dans lequel on définira les clés et les chaînes associées. On place généralement les fichiers de traduction dans <app>/theme/i18n/local/. Par exemple on créera le fichier <app>/theme/i18n/local/module-monModule.xml avec le contenu minimum suivant :

<?xml version="1.0" encoding="UTF-8"?>
<catalogue xmlns:xhtml="http://www.w3.org/1999/xhtml">
    <message key="monModule.maCle">La chaine à afficher</message>
    <!-- ... -->
</catalogue>

Déclarer le catalogue à l'application

Ensuite, il faut déclarer à l'application la présence de notre nouveau catalogue, de façon à pouvoir trouver les traductions de nos clés. On surchargera le fichier <app>/catalogues-i18n.xmap de façon à indiquer à l'application le chemin vers les nouveaux fichiers de traductions.

Catalogues et transformeur

Le catalogue que vous rajouter doit être placer dans le <map:transformer> dont l'attribut name correspond à celui que vous appeler dans votre pipeline. Ci-dessous un pipeline faisant appel au transformateur prefixI18n-normal :

<map:act type="locale">
    <map:transform type="prefixI18n-normal">
        <map:parameter name="locale" value="{locale}"/>
    </map:transform>
</map:act>

On déclarera donc notre catalogue dans le transformateur prefixI18n-normal du fichier <app>/catalogues-i18n.xmap :

<map:transformer name="prefixI18n-normal" logger="sitemap.transformer.prefixI18n" src="org.pleade.transformation.PrefixI18nTransformer">
...
</map:transformer>

Ajout du catalogue

Une fois le bon tranformateur trouvé, on rajouter notre catalogue de la façon suivante :

<!-- Catalogue spécifique au module monModule -->
<catalogue id="module-monModule" name="module-monModule">
  <location>${pleade.theme-dir}/i18n/local</location>
  <location>${pleade.theme-dir}/i18n</location>
</catalogue>

Voir aussi

• I18n Transformer (doc officiel)
• Class I18nTransformer (spécification Java)

Références

<references/>