Internationalisation (i18n)

Présentation

Il est possible d’adapter le contenu d’une application Lutèce en fonction du contexte de l’utilisateur (langue, pays…). Pour cela, Lutèce s’appuie sur les recommandations et les outils proposés par la plateforme Java. Les textes manipulés par l’application sont remplacés par des clés répertoriées dans des fichiers “properties” où elles sont associées à un libellé. Les mêmes clés sont reprises dans différents fichiers avec un suffixe précisant le contexte. Par exemple :

myplugin_messages.properties - langue par défaut
myplugin_messages_fr.properties - Français
myplugin_messages_fr_FR.properties - Français (France)
myplugin_messages_en_CA.properties - Français (Canada)
myplugin_messages_en_US.properties - Anglais (États-Unis)
…

Lors de la création du contenu, le fichier est sélectionné par la classe ResourceBundle en fonction de la locale définie pour l’utilisateur (variable représentant un contexte, notamment basé sur une langue et un pays).

Règles des fichiers et des clés

Afin que Lutèce puisse déterminer dans quel fichier rechercher une clé, le nom et l’emplacement des fichiers de ressources sont soumis aux règles suivantes selon le type de composant :

Type de composant	Emplacement du fichier	Construction de la clé
Sous-système Core Lutece	`src/java/fr/paris/lutece/portal/resources/<subsystem>_messages.properties`	`portal.<subsystem>.<template>.<label>`
Plugin	`src/java/fr/paris/lutece/<plugin>/resources/<plugin>_messages.properties`	`<plugin>.<template>.<label>`
Module d’un Plugin	`src/java/fr/paris/lutece/<plugin>/modules/<module>/resources/<module>_messages.properties`	`module.<plugin>.<module>.<template>.<label>`

où :

<subsystem> est un nom donné au sous-système Core
<plugin> est un nom donné au plugin
<module> est un nom donné au module
<template> est un nom donné au template dans lequel le libellé sera utilisé (ex : create_document)
<label> est un nom donné au libellé (ex : labelDocumentTitle)

Internationalisation dans les templates

Vous devez indiquer l’emplacement des libellés à internationaliser dans les templates en insérant #i18n suivi de la clé i18n correspondant au libellé entre accolades :

<h2>#i18n {document.create_document.title} ${document_type}</h2>
<div class="form-group">
  <p>
    <label for="document_title">#i18n {document.create_document.labelDocumentTitle} * :</label>
    <input type="text" name="document_title" size="80" maxlength="255"/>
    <span class="help-block">#i18n {document.create_document.helpDocumentTitle}</span>
  </p>
</div>

Labels i18n avec paramètres

Il est possible de passer des paramètres à un libellé i18n en utilisant le pattern de la classe Java MessageFormat dans le fichier de ressources myplugin_messages.properties :

mykey.message = Mon message utilisant 2 arguments: {0} et {1}

Voir dans la documentation Java les particularités de MessageFormat, notamment concernant l’échappement (les guillemets simples doivent, par exemple, être doublés pour être correctement pris en compte : mykey.message=Affichons l''argument {0}).

Le #i18n est remplacé par ${i18n("key", arg1, ...)} comme suit :

${i18n("myplugin.mykey.message", argument1, argument2)}

Internationalisation dans le code Java

Dans le code Java, utilisez le service I18nService pour localiser une clé en fonction de la locale courante. Les valeurs des clés doivent être déclarées dans des constantes comme ci-dessous :

private static final PROPERTY_MESSAGE_MYMESSAGE = "myplugin.myMessage";

...
String strLocalizedMessage = I18nService.getLocalizedString(PROPERTY_MESSAGE_MYMESSAGE, locale);
...

Surcharge des valeurs i18n

Les valeurs par défaut des clés i18n peuvent être surchargées dans des fichiers placés sous /WEB-INF/conf/override/ (par défaut) et respectant la même arborescence. Ainsi pour surcharger des clés de myplugin_messages.properties, il faudra les placer dans /WEB-INF/conf/override/fr/paris/lutece/myplugin/resources/myplugin_messages.properties.

Il n’est pas nécessaire de redéfinir toutes les clés dans ces fichiers. Un mécanisme permet de récupérer les clés du fichier original lorsqu’elles n’ont pas été redéfinies.