Historique de la page

L'internationalisation est native dans esup-commons. L'intérêt n'est pas seulement de fournir une application en plusieurs langages... L'externalisation de toutes les chaînes de caractères et la possibilité d'utiliser simultanément plusieurs fichiers de chaînes (les bundles) permettent de simplifier la personnalisation des applications par les administrateurs.

Sommaire :

...

...

...

Principes

Configuration

L'internationalisation est définie dans le fichier de configuration /properties/i18n/i18n.xml. On y trouvera par exemple :

<bean
    id="i18nService"
    class="[org.esupportail..].commons.services.i18n.BundlesCachingI18nServiceImplResourceBundleMessageSourceI18nServiceImpl">
  <property name="messageSource" ref="msgs" />
</bean>

<bean id="msgs"
 <property nameclass="bundleBasenamesorg.esupportail.commons.services.i18n.ReloadableResourceBundleMessageSource">
  <!--  <list>
      <value>propertiesorg.esupportail.commons.services.i18n.ReloadableResourceBundleMessageSource since 0.3.3
       org.springframework.context.support.ReloadableResourceBundleMessageSource before -->
  <property name="basenames">
    <list>
      <value>classpath:properties/i18n/bundles/Commons<Custom</value>
      <value>properties     <value>classpath:properties/i18n/bundles/Messages</value>
      <value>properties     <value>classpath:properties/i18n/bundles/Custom<Commons</value>
value>               < 
    </list>
  </property> </property>
  <property name="cacheSeconds" value="60" />
</bean>

...

i18nService

• La propriété messageSource fait référence à l'implémentation Spring du son mécanisme de ResourceBundleMessageSource

msgs

• Le nom du bean lui même est important car il est notamment utilisé dans les vues JSF
• La propriété basenames donne la liste des fichiers de messages à utiliser. Chaque valeur de la liste correspond

...

• au chemin du fichier de message dans le classpath. Par exemple, on cherchera pour la valeur Custom les fichiers Custom_<locale>.properties ou à défaut Custom.properties. Par convention, on groupera tous les fichiers de messages dans le répertoire /properties/i18n/bundles.
• La propriété cacheSeconds donne le délai en entre cache relecture des fichiers de messages

Implémentations disponibles

esup-commons offre plusieurs implémentations afin de gérer l'internationalisation des applications :

• ResourceBundleMessageSourceI18nServiceImpl utilise l'implémentation Spring du son mécanisme de ResourceBundleMessageSource (depuis ESUP-Commons 2 - 0.2.7)

Les autres implémentations sont conservées pour des raisons de compatibilité mais devrait disparaître à terme :

• BundleI18nServiceImpl lit les chaînes de caractères depuis un unique fichier de messages.
• BundleCachingI18nServiceImpl étend BundleI18nServiceImpl. Elle permet la mise en cache des chaînes de caractères lues depuis le fichier de messages, pour des raisons de performance.
• BundlesI18nServiceImpl lit les chaînes de caractères depuis plusieurs fichiers de messages.
• BundlesCachingI18nServiceImpl étend BundlesI18nServiceImpl en apportant des fonctionnalités de cache, pour les mêmes raisons de performance.

C'est cette dernière implémentation qui est généralement conseillée car elle permet la personnalisation locale des applications par les administrateurs sans modifier les fichiers distribués par les développeurs.

Préconisations d'usage

Nommage des bundles

Les fichiers de messages sont lus dans l'ordre où ils apparaissent dans le fichier de configuration. Chaque entrée d'un fichier de message peut être surchargée par la même entrée définie dans le fichier suivantprécédent. En effet, c'est la première définition d'une entrée qui compte.

Les fichiers Commons_.properties font partie du projet esup-commons, ils ne doivent pas être modifiés par les développeurs d'applications.

...

Les fichiers Custom_.poperties* permettent à l'exploitant de surcharger les messages livrés avec l'application (qu'il s'agisse de messages de esup-commons ou de l'application). Typiquement, ce fichier devrait être repris par la tâche ant recover-config lors d'une mise à jour. Pour cela, l'exploitant ajoutera une entrée correspondant à ce fichier dans le paramètre custom.recover.files de son fichier build.properties.

WELCOME.TITLE = Bienvenue

WELCOME.TITLE = Bienvenue sur l'application de formation.

Modification des fichiers de messages

Pour modifier les fichiers de messages il est recommandé d'utiliser Ressource Bundle Editor (RBE). Il permet notamment d'éditer plusieurs fichiers, correspondants à plusieurs langues, en même temps. Les messages enregistrés dans ces fichiers peuvent contenir des paramètres qui seront dynamiquement renseignés lors de l'exécution. Ces paramètres apparaissent dans les messages sous cette forme :

{n}

avec n commençant à 0. Exemple :

L''utilisateur {0} est maintenant gestionnaire du service {1}.

L''utilisateur {0} est maintenant gestionnaire du service {1,choice,0#annuaire|1#helpdesk}.

Ajout d'un langage

...

Externalisation des chaînes sans internationalisation

...

Utilisation

Dans une vue

JSF

La balise <f:view> propose un attribut locale qui permet de spécifier la langue à utiliser. Cette information est généralement donnée par un contrôleur. On trouvera par exemple en entête des pages :

<f:view locale="#{sessionController.locale}">

La balise <f:view> positionnera un tableau associatif qui contiendra tous les messages de messages. Ce tableau sera accessible sous le nom msgs et est utilisable dans toute la vue, par exemple :

Dans le fichier faces-config.xml il faut ajouter à la définition de l’application le resolver d'expression suivant :

<el-resolver>org.esupportail.commons.jsf.ResourceBundleFacesELResolver</el-resolver>

Le bean msgs défini dans le fichier /properties/i18n/i18n.xml sera alors accessible dans les pages JSF. Exemple :

<h:outputText

<e:text value="#{msgs['MANAGERS.TEXT.PAGESDEEPLINKING_DEMO.GENERATE_URL.PARAM_NAME']}">
  <f:param value="#{controller.paginator.firstVisibleNumber + 1}"/>
  <f:param value="#{controller.paginator.lastVisibleNumber + 1}"/>
  <f:param value="#{controller.paginator.totalItemsCount}"/>
</e:text>

Les balises <f:param> permettent de passer les valeurs des paramètres à insérer dans les messages.

Spring MVC

 />

Ajout d'un langage

L'ajout d'un langage se fait dans le fichier de configuration src/main/webapps/WEB-INF/jsf/faces-config.xml. Exemple :

<locale-config>
  <default-locale>fr</default-locale>
  <supported-locale>fr</supported-locale>
  <supported-locale>en</supported-locale>
</locale-config>

Il suffit ensuite d'écrire le bundle correspondant.

Accès depuis

...

un contrôleur (Java)

Par héritage, toute classe (métier ou contrôleur) qui étend AbstractApplicationAwareBean bénéficie des services de AbstractI18nAwareBean et peut appeler ses méthodes d'internationalisation.

 
On utilise cela en particulier pour les messages (d'information ou d'erreur) lancés par les contrôleurs et affichés sur les vues JSF à l'aide de la balise <h:messages>. On utilisera par exemple :

addErrorMessage(null, "MANAGERS.MESSAGE.USER_NOT_FOUND", userId);

On utilisera également cette fonctionnalité à toute autre fin en accédant directement aux fichiers de messages de cette manière :

String msg = getString("MY.MESSAGE");

On peut également passer des paramètres à la méthode getString(), ainsi qu'une locale (si l'on souhaite une locale différente de la locale courante), qui est donnée par ma méthode getLocale().

Changement des messages d'erreur par défaut de JSF

Pour modifier les messages d'erreurs par défaut ou les internationaliser, il faut écrire un fichier JsfMessage_fr.properties dans le répertoire /properties/i18n/bundles et ajouter :

<message-bundle>properties/i18n/bundles/JsfMessages</message-bundle>

...

Par exemple lorsque l'on utilise les validations implicites avec l'attribut required="true" au lieu d'avoir le message « une donnée est requise », on pourra avoir un message personnalisé en indiquant les messages suivants dans le fichier JsfMessages.properties :

javax.faces.component.UIInput.REQUIRED = Erreur de validation
javax.faces.component.UIInput.REQUIRED_detail = "et {0} alors !!!

Spring MVC

Spring MVC nécessite que le bean implémentant MessageSource porte l'id messageSource. Dans l'exemple ci-dessus vous pouvez changer msgs en messageSource ou définir un alias :

<alias name="msgs" alias="messageSource"/>

Ensuite dans la vue vous accédez aux messages avec ce type de code :

<%@ taglib prefix="spring" uri="http://www.springframework.org/tags" %>
<h1><spring:message code="title"/></h1>
<spring:message code="messageWithParam" arguments="${param1},${param2}"/>