Internationalisation (i18n)
Présentation
Il est possible d'adapter le contenu d'une application Lutèce en fonction du contexte de l'usager (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 listées dans des fichiers "properties" où ils sont associés à un libellé. Les mêmes clés sont reprises dans différents fichiers ayant un suffixe précisant le contexte. Par exemple :
- myplugin_messages.properties - langage par défaut
- myplugin_messages_fr.properties - français
- myplugin_messages_fr_FR.properties - français (France)
- myplugin_messages_fr_CA.properties - français (Canada)
- myplugin_messages_en_US.properties - anglais (Etats-Unis)
- ...
A 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 concernant les fichiers et les 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 des fichiers | Construction de la clé |
|---|---|---|
| Sous-système du Core Lutèce | 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> |
dans lequel :
- <subsystem> est un nom donné au sous-système du Core
- <plugin> est un nom donné au plugin
- <module> est un nom donné au module
- <template> est un nom donné au template dans lequel sera utilisé le libellé (ex : create_document)
- <label> est un nom donné au libellé (ex : labelDocumentTitle)
Internationalisation dans les templates
Il faut 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>
...Libellés i18n avec paramètres
Nouveau LUTECE v5.0
Il est possible de passer des paramètres à un libellé i18n utilisant le motif (pattern) de la classe Java MessageFormat dans le fichier de ressources myplugin_messages.properties :
mykey.message=My message using 2 arguments : {0} and {1}Attention ! Voir dans la documentation Java les particularités de MessageFormat, notamment ce qui concerne l'échappement (les guillemets simple doivent par exemple être doublés pour être correctement pris en compte : mykey.message=L''affiche de {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, il faut recourir au 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 de valeurs i18n
Nouveau LUTECE v5.0
Les valeurs par défaut des clés i18n sont surchargeables 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 d'origine lorsqu'elles n'ont pas été redéfinies.