SeamFramework.orgCommunity Documentation

Chapitre 16. Internationnalisation, les langues locales et les thèmes

16.1. Internationnalisation de votre application.
16.1.1. La configuration du serveur d'application
16.1.2. Les chaines de caractères de l'application traduites
16.1.3. D'autres réglages pour l'encodage
16.2. Les locales
16.3. Les labels
16.3.1. La définition des labels
16.3.2. L'affichage des labels
16.3.3. Les messages Faces
16.4. Les fuseaux horaires
16.5. Les thèmes
16.6. La préservation des préférences de langue et de thème via des cookies

Seam rend facile la construction d'applications internationnalisées? En premier, regardons toutes les étapes nécéssaires pour internationnaliser et rendre avec une langue locale votre application. Ensuite nous allons regarde les composants livrés dans Seam.

Une application JEE consisten en plusieurs composants et tous doivent être configurés de manière appropriés pour que votre application soit traduisible.

En partant du bas, la première étape est de s'assrer que le serveur de base de données et le client utilise le bon encodage de caractères pour votre langue. Normallement, vous devriez vouloir utiliser UTF-8. Comment faire cela est hors de porté de ce tutorial.

Vous allez avoir besoin des chaines de caractères traduites pour tous les messages de votre applicatin (par exemple les labels des champsd e vos vues). En premier, vous alleza avoir besoin de vous assurer que vos fiches de ressources sont encodés avec l'encodage désiré. Par défaut, l'ASCII est utilisé. Mais l'ASCII n'est pas suffisant pour beaucoups de langues, il ne fourni pas toutes les lettres de tous les langages.

Les fichiers de ressource doivent être créés en ASCII ou utiliser le code déspécialisé Unicode pour représenter les lettres Unicode. Sinon vous ne pourez pas compiler le fichier de propriété dans le byte-code, il n'y a pas de moyen pour indiquer à la JVM quel groupe de caractères utiliser. Donc vous devez utiliser soit les caractères ASCII soi des caractères déspécialisés qui ne sont pas dans le groupe des caractères de l'ASCII. Vous pouvez représenter un caractère Unicode dans le fichier en Java en utilisant \uXXX, où XXX est la représentation hexadécimale de ce caractère.

Vous pouvez écrire votre traductions des labels (Section 16.3, « Les labels ») dans vos fichiers de ressource dans l'encodage natif et ensuite la conversation du fichier dans le format déspécialisé avec l'outil native2ascii fourni dans le JDK. Cet outil va convertir un fichier écrit dans votre encodage natif dans un nouveau où la représentation des caractères non-ASCII sera en séquence déspécialisé Unicode.

L'utilisation de cet outil est décrit dans ici pour Java 5 ou ici pour Java 6. Par exemple, pour convertir un fichier depuis UTF-8:

$ native2ascii -encoding UTF-8 messages_cs.properties > messages_cs_escaped.properties

Chaque session de connection de l'utilisateur est associé avec une instance de java.util.Locale (disponible dans l'application comme un composant appelé locale). Dans les circonstances normales, vous n'avez pas besoin de définir la locale. Seam va simplement déléguer à JSF le fait de déterminer la locale active:

C'est possible de définir la langue manuellement via les propriétés de configuration de Seam org.jboss.seam.international.localeSelector.language, org.jboss.seam.international.localeSelector.country et org.jboss.seam.international.localeSelector.variant, mais nous n'avons pas trouver de bonne raison d'avoir à faire cela.

C'est, cependant, utile de permettre à l'utilisateur de définir sa langue manuellement via un interface utilisateur de l'application. Seam fourni une fonctionnalité livrée pour remplacer la langue déterminée par l'algorithme ci-dessus. Tout ce que vous avez à faire est d'ajouter le fragment suivant dans un formulaire de votre page JSP ou Facelets:


<h:selectOneMenu value="#{localeSelector.language}">
    <f:selectItem itemLabel="English" itemValue="en"/>
    <f:selectItem itemLabel="Deutsch" itemValue="de"/>
    <f:selectItem itemLabel="Francais" itemValue="fr"/>
</h:selectOneMenu>
<h:commandButton action="#{localeSelector.select}"
    value="#{messages['ChangeLanguage']}"/>

Ou si vous voulez une liste de toutes les langues supportées depuis faces-config.xml, utilisez simplement :


<h:selectOneMenu value="#{localeSelector.localeString}">
    <f:selectItems value="#{localeSelector.supportedLocales}"/>
</h:selectOneMenu>
<h:commandButton action="#{localeSelector.select}"
    value="#{messages['ChangeLanguage']}"/>

Quand l'utilisateur sélectionne un élément depuis cette liste, ensuite il clique sur le bouton de commande, alors les lagues de Seam et de JSF vont être remplacées pour le reste de la session.

Pour répondre à la question à quel endroit les langues sont-elle définies. Typiquement, vous fournissez une liste de langues pour lesquelles vous avez un fichiers de ressources correspondant dans l'élément <locale-config> de fichier de configuration JSF (/META-INF/faces-config.xml). Cependant, vous avez appris à apprécier le mechanisme de configuration des composants de Seam qui est plus psuissant que celui fourni dans Java EE. Pour cette raison, vous pouvez configurer les langues supportées, et une langue par défaut sur le serveur, en utilisant le composant livré dénommé org.jboss.seam.international.localeConfig. Pour l'utiliser, vous déclarer en premier un espace de nommage XML pour le paquet international de Seam dans le descripteur du composant de Seam. Vous définissez ensuite une langue par défaut et les langues supportées comme ci-dessous:


<international:locale-config default-locale="fr_CA" supported-locales="en fr_CA fr_FR"/>

Naturellement, si vous déclarrez que vous supporté une langue, vous devriez fournir un fichier de ressource qui lui correspond! Ensuite, vous allez apprendre comment définir des labels spécifiques aux langues.

JSF permet une internationnalisation des labels des interfaces utilisateurs et des texte descriptif via l'utilisation de <f:loadBundle />. Vous pouvez utilisez cette approche dans les application Seam. Au alternative, vous pouvez profiter du composant messages de Seam pour afficher les labels modèles avec les expressions EL embarquées.

Seam fourni unjava.util.ResourceBundle (disponible pour l'application comme un org.jboss.seam.core.resourceBundle). Vous allez avoir besoin de rendre les labels à internationnaliser disponible via ce fichier de ressource spécial. Par défaut, le fichier de ressource utilisé par Seam est appelé messages et donc vous allez avoir besoin de définir vos labels dans des fichiers appelés messages.properties, messages_en.properties, messages_en_AU.properties, etc. Ces fichiers vont habituellement dans le dossier WEB-INF/classes.

Ainsi, dans messages_en.properties:

Hello=Hello

Et dans messages_en_AU.properties:

Hello=G'day

Vous pouvez sélectionner un nom différent pour le fichier de ressource en définissant dans la propriété de configuration de Seam dénommée org.jboss.seam.core.resourceLoader.bundleNames. Vous pouvez même spécifie une liste de fichier de ressources à chercher (premier trouvé, premier servi) pour les messages.


<core:resource-loader>
    <core:bundle-names>
        <value>mycompany_messages</value>
        <value>standard_messages</value>       
    </core:bundle-names>
</core:resource-loader>

Si vous voulez définir un message juste pour une page particulière, vous pouvez le spécifier dans le fichier de ressource avec le m^me nom que l'identifiant de la vue JSF, avec un / devant et en enlevant l'extension du nom de fichier. Ainsi vous pouvez mettre notre message dans welcome/hello_en.properties si vous avez seulement besoin d'afficher le message sur /welcome/hello.jsp.

Vous pouvez même spécifier un nom de fichier explicite dans pages.xml:


<page view-id="/welcome/hello.jsp" bundle="HelloMessages"/>

Ensuite, nous pourions utiliser les messages définie dans HelloMessages.properties avec /welcome/hello.jsp.

Il y aussi une instance d'étendue de session dénommé java.util.Timezone, dénommée org.jboss.seam.international.timezone, et un composant de Seam pour la modificaiton du fuseau horaire dénommé org.jboss.seam.international.timezoneSelector. Par défaut, le fuseau horaire est le fuseau horaire par défaut du serveur. Malheureusement, la spécification JSF indique que toute les dates et les heures devraient être en UTC, et affichées en UTC, à moins que le fuseau horaire ne soit spécifié en utilisant <f:convertDateTime>. Ceci est un inconvénient majeur pour une fonctionnalité par défaut.

Seam remplace cette fonctionnalité et par défaut, toutes les dates et les heures sont du fuseau horaire de Seam. De plus, Seam fourni une balise <s:convertDateTime> qui réalise toujours une conversation dans le fuseau horaire de Seam.

Seam fourni aussi un convertisseur de date par défaut convertissant une valeur de chaine de caractères vers une date. Ceci vous préserve d'avoir à indiquer un convertisseur pour les champs de saisies qui sont simplement capturé comme des dates. Le patron est sélectionné en accord avec la langue de l'utilisateur et son fuseau horaire est sélectionné comme décrit ci-dessous.

Les applications de Seam sont aussi très facilement personnalisable. L'API des thèmes est vraiment similaire à l'API de localisation, mais bien sur ces deux concernes de sujets orthogonaux et quelques application ont à la fois la localisation et les thèmes.

En permier, configurez le groupe de thème disponibles:


<theme:theme-selector cookie-enabled="true">
    <theme:available-themes>
        <value>default</value>
        <value>accessible</value>
        <value>printable</value>
    </theme:available-themes>
</theme:theme-selector>

Notez que le premier thème listé est le thème par défaut.

Les thèmes sont définies dans un fichier de propriétés avec le même nom que le thème. par exemple, le thème default est définie comme un groupe d'entréees dans default.properties. Par exemple, default.properties devrait définir:

css ../screen.css
template /template.xhtml

Habituellement, un fichier de ressource de thème aura des chemins vers des fichiers de styles CSS ou des images ou des noms de pattron de facelets (à la différence des fichiers de resource de la localisation qui sont habituellement des fichiers textes).

Maintenant, nous pouvons utiliser ces entrées dans nos pages JSP ou facelets. par exemple, pour personnaliser la feuille de style dans une page facelets:


<link href="#{theme.css}" rel="stylesheet" type="text/css" />

Ou, quand la définition de la page réside dans un sous-dossier:


<link href="#{facesContext.externalContext.requestContextPath}#{theme.css}" 
    rel="stylesheet" type="text/css" />

Plus impressionnant, les facelets nous permette de personnaisée le pattron utilisé avec un <ui:composition>:


<ui:composition xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:f="http://java.sun.com/jsf/core"
    template="#{theme.template}">

Toute comme le sélectioneur de langue, il y a un sélectionneur de thème livré qui permet à l'utilisateur de librement basculer entre les thèmes:


<h:selectOneMenu value="#{themeSelector.theme}">
    <f:selectItems value="#{themeSelector.themes}"/>
</h:selectOneMenu>
<h:commandButton action="#{themeSelector.select}" value="Select Theme"/>

Le sélectionneur de langue, le sélectionneur de thème et le sélectionneur de fuseau horaire supportent tous la persistance de la rpéférence vers un cookie. En simplement définissant la propriété cookie-enabled dans components.xml:


<theme:theme-selector cookie-enabled="true">
    <theme:available-themes>
        <value>default</value>
        <value>accessible</value>
        <value>printable</value>
    </theme:available-themes>
</theme:theme-selector>

<international:locale-selector cookie-enabled="true"/>