SeamFramework.orgCommunity Documentation
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.
Note that all i18n features in Seam work only in JSF context.
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.
Pour s'assurer que le serveur d'application reçoit les paramètres dans l'encodage correct depuis les requêtes client, vous devez configurer le connecteur de tomcat. Si vous utilisez Tomcat ou JBoss AS, ajoutez l'attribut URIEncoding="UTF-8"
à la configuration du connecteur. Pour JBoss AS 4.2, modifiez ${JBOSS_HOME}/server/(default)/deploy/jboss-web.deployer/server.xml
:
<Connector port="8080" URIEncoding="UTF-8"/>
Il ya une alternative qui est probablement meilleure. Vous pouvez dire à JBoss AS que l'encodage des paramètres des requeêtes sera prit depuis la requête:
<Connector port="8080" useBodyEncodingForURI="true"/>
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
Soyez sur que les vues affichant vos informations localisées et les message utilisent le bon groupe de caractères et aussi que toute donnée soumise utilise le bon encodage.
Pour définir l'encodage de caractère à afficher, vous devez utiliser la balise <f:view locale="cs_CZ"/>
(ici pour dire à JSF d'utiliser la langue Tchèque). Vous pouvez vouloir modifier l'encodage du document xml lui-même si vous voulez embarqué des chaines de caractères localisées en xml. Pour faire cela, modifiez l'attriut d'encodage dans la déclaration xml <?xml version="1.0" encoding="UTF-8"?>
selon le besoin.
De plus JSF/Facelets devrait soumettre toutes les requêtes en utilisant l'encodage de caractères spécifié, mais pour êtrer sur que toutes les requêtes ne vont pas indiquer un encodage vous pouvez obliger l'encodage de la requête en utilisant un filtre servlet. Vous configurez cela dans components.xml
:
<web:character-encoding-filter encoding="UTF-8"
override-client="true"
url-pattern="*.seam" />
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:
S'il ya une langague associée avec la requête HTTP (la langue du navigateur), et que la langue est dans la liste des langues supportées dans le faces-config.xml
, utilisez cette langue pour le reste de la session.
Cependant, si la langue a été spécifiée dans le faces-config.xml
, alors utilise cette langue pour le reste de la session.
Sinon, utilise la locale par défaut du serveur.
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
.
Si vous définissez vos labels en utilisant le fichier de ressource de Seam, vous allez être capable de les utiliser sans avoir à indiquer <f:loadBundle ... />
sur chaque page. Au lieu de cela, vous pouvez simplement indiquer:
<h:outputText value="#{messages['Hello']}"/>
ou:
<h:outputText value="#{messages.Hello}"/>
Même mieux, les mesages eux-même peuvent contenir des expressions EL:
Hello=Hello, #{user.firstName} #{user.lastName}
Hello=G'day, #{user.firstName}
Vous pouvez même utiliser les messages dans votre code:
@In private Map<String, String> messages;
@In("#{messages['Hello']}") private String helloMessage;
Le composant facesMessages
est une façon super-simplifiée d'afficher un message de réussite ou d'echec à l'utilisateur. La fonctionnalité que nous avons juste à l'instant décrit fonctionne aussi avec les messages faces:
@Name("hello")
@Stateless
public class HelloBean implements Hello {
@In FacesMessages facesMessages;
public String sayIt() {
facesMessages.addFromResourceBundle("Hello");
}
}
Cela va afficher Hello, Gavin King
ou G'day, Gavin
, selon la locale de l'utilisateur.
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"/>