From seam-commits at lists.jboss.org Mon May 12 06:34:50 2008 Content-Type: multipart/mixed; boundary="===============3207919548214066926==" MIME-Version: 1.0 From: seam-commits at lists.jboss.org To: seam-commits at lists.jboss.org Subject: [seam-commits] Seam SVN: r8161 - branches/Seam_2_0/doc/Seam_Reference_Guide/en-US. Date: Mon, 12 May 2008 06:34:47 -0400 Message-ID: --===============3207919548214066926== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: manaRH Date: 2008-05-12 06:34:47 -0400 (Mon, 12 May 2008) New Revision: 8161 Modified: branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/I18n.xml Log: JBSEAM-2712 Modified: branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/I18n.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/I18n.xml 2008-05-12 10= :28:43 UTC (rev 8160) +++ branches/Seam_2_0/doc/Seam_Reference_Guide/en-US/I18n.xml 2008-05-12 10= :34:47 UTC (rev 8161) @@ -1,201 +1,266 @@ - + + + Internationalization, localization and themes = - - Internationalization and themes - - Seam makes it easy to build internationalized applications by - providing several built-in components for handling multi-language - UI messages. - - = + Seam makes it easy to build internationalized applications. First, + let's walk through all the stages needed to internationalize and localize + your app. Then we'll take a look at the components Seam bundles. + +
+ Internationalizing your app + + JEE application is consisting from many components and all can b= reak + the whole view on the localizated target. + + Starting at the bottom, the first step is to ensure that your + database server and client is using the correct character encoding for + your locale. Normally you'll want to use UTF-8. How to do this is outs= ide + the scope of this tutorial. +
- Locales - - Each user login session has an associated instance of - java.util.Locale (available to the = - application as a component named = - locale). Under normal circumstances, - you won't need to do any special configuration to set - the locale. Seam just delegates to JSF to determine - the active locale: - - = - - - If there is a locale associated with the HTTP request - (the browser locale), and that locale is in the list - of supported locales from faces-config.xml, = - use that locale for the rest of the session. - - - Otherwise, if a default locale was specified in the - faces-config.xml, use that locale = - for the rest of the session. - - - Otherwise, use the default locale of the server. - - - = - - It is possible to set the locale - manually via the Seam configuration properties - org.jboss.seam.international.localeSelector.language<= /literal>, - org.jboss.seam.international.localeSelector.country and - org.jboss.seam.international.localeSelector.variant, but = - we can't think of any good reason to ever do this. - - = - - It is, however, useful to allow the user to set the - locale manually via the application user interface. - Seam provides built-in functionality for overriding - the locale determined by the algorithm above. All - you have to do is add the following fragment to a = - form in your JSP or Facelets page: - - = - - - - - -]]> + Application server configuration = - - Or, if you want a list of all supported locales from = - faces-config.xml, just use: - + To ensure that application server receive correct parameters + attributes from client requests you have to adapt the configuration = of + tomcat connector. If you use Tomcat or JBOSS AS, add attribute + URIEncoding=3D"UTF-8" into connector configuration. In = case + JBOSS AS 4.2.2 change + ${JBOSS_HOME}/server/(default)/deploy/jboss-web.deployer/serve= r.xml + configuration file like the following: = - - - -]]> + <Connector port=3D"8080" URIEncoding=3D"UTF-8"/&g= t; = - - When this use selects an item from the drop-down, and = - clicks the button, the Seam and JSF locales will be = - overridden for the rest of the session. - - = + There is also another configuration atribute + useBodyEncodingForURI, which is logically better for us= e, + because it says that encoding for URI will be taken from setting of = web + page body. In other words the encoding of the parameters in URL will= be + same as the content of the web page. Example of configuration is the + following: + + <Connector port=3D"8080" useBodyEncodingForURI=3D= "true"/>
- = +
- Labels - - JSF supports internationalization of user interface labels and - descriptive text via the use of <f:loadBundle />= ;. - You can use this approach in Seam applications. Alternatively,= you can - take advantage of the Seam messages compone= nt to = - display templated labels with embedded EL expressions. - - = + Translated application strings + + Correct localized application uses for all static texts in JSF + pages labels, which can be translated and loaded from resource bundl= es + with defined labels. First you need to ensure that your resource bun= dle + is encoded using the desired character encoding. By default it uses + ISO-8859-1. Although ISO-8859-1 supports many languages, it doesn't + represent everything. So if you want to translate in another languga= ge, + which uses characters outside the standard ASCII set, you need to use + encoding which covers all these non-ascii characters. + + You'll need to understand another caveat regarding property + bundles; you must create them in ASCII, or use Unicode escape codes = to + represent Unicode characters. Since you don't compile a property fil= e to + byte codes, there is no way to tell the JVM which character set to u= se. + So you must explicitly use ASCII characters or use the escape sequen= ces. + You can represent a Unicode character in any Java file using \uXXXX, + where XXXX is the hexidecimal representation of the character. Write + your translation of labels (see below section Labels) to file and then you have to conve= rt the + content of file into escaped format through the java command tool + native2ascii provided in the JDK. This tool will convert a file writ= ten + in your native encoding to one that represents non-ASCII characters = as + Unicode escape sequences. + + Usage of this tool is described at http://java.sun.com/j2se/1.5.0/docs/tooldocs/index.html#intl + for Java 5 or at http= ://java.sun.com/javase/6/docs/technotes/tools/#intl + for Java 6, but briefly, on command line write:$ native2ascii -encoding UTF-8 messages_cs.properties > message= s_cs_escaped.propertiesThen + converted file can be used in application as resource bundle with a + proper locale code (see Labels). +
+
- Defining labels - - Seam provides a java.util.ResourceBundle (a= vailable = - to the application as a org.jboss.seam.core.resourceB= undle). = - You'll need to make your internationalized labels available vi= a this special = - resource bundle. By default, the resource bundle used by Seam = is named = - messages and so you'll need to define your = labels = - in files named messages.properties, = - messages_en.properties, - messages_en_AU.properties, etc. These - files usually belong in the WEB-INF/classes = - directory. - - = - - So, in messages_en.properties: - - = - + Other encoding settings = - - And in messages_en_AU.properties: - - = - - = - - You can select a different name for the resource bundle by set= ting - the Seam configuration property named - org.jboss.seam.core.resourceLoader.bundleNames. You can even specify - a list of resource bundle names to be searched (depth first) f= or - messages. - + We need to make sure that the view (JSF, JSP or XHTML) displays + your correct localized data and messages using the correct character= set + and also any data submitted uses the correct encoding. = - - - mycompany_messages - standard_messages = - -]]> + To set the display character encoding, you need to use the + <f:view locale=3D"cs_CZ"/> tag for example = to use + Czech locale in Java Server Faces technology. You may want to change= the + encoding of the xml document itself if you want to embed localized + strings in the xml. To do this alter the encoding attribute in xml + declaration <?xml version=3D"1.0" + encoding=3D"UTF-8"?> as required. = - - If you want to define a message just for a particular page, you - can specify it in a resource bundle with the same name as the - JSF view id, with the leading / and trailing - file extension removed. So we could put our message in = - welcome/hello_en.properties if we only need= ed - to display the message on /welcome/hello.jsp. - - = - - You can even specify an explicit bundle name in pages= .xml: - - = - ]]> - = - - Then we could use messages defined in HelloMessages.p= roperties - on /welcome/hello.jsp. - + Also JSF/Facelets should submit any requests in the desired + character, but to make sure any requests that don't specify an encod= ing + you can use a Servlet filter to set it in Seam components.xml + configuration file: + + <web:character-encoding-filter encod= ing=3D"UTF-8" = + override-client=3D"true" = + url-pattern=3D"*.seam"/>
- = +
+ +
+ Locales<anchor id=3D"locales" /> + + Each user login session has an associated instance of + java.util.Locale (available to the application as a + component named locale). Under normal circumstances, + you won't need to do any special configuration to set the locale. Seam + just delegates to JSF to determine the active locale: + + + + If there is a locale associated with the HTTP request (the + browser locale), and that locale is in the list of supported local= es + from faces-config.xml, use that locale for the = rest + of the session. + + + + Otherwise, if a default locale was specified in the + faces-config.xml, use that locale for the rest = of + the session. + + + + Otherwise, use the default locale of the server. + + + + It is possible to set the locale manually v= ia + the Seam configuration properties + org.jboss.seam.international.localeSelector.language, + org.jboss.seam.international.localeSelector.country and + org.jboss.seam.international.localeSelector.variant, + but we can't think of any good reason to ever do this. + + It is, however, useful to allow the user to set the locale manua= lly + via the application user interface. Seam provides built-in functionali= ty + for overriding the locale determined by the algorithm above. All you h= ave + to do is add the following fragment to a form in your JSP or Facelets + page: + + <h:selectOneMenu value=3D"#{localeSe= lector.language}"> + <f:selectItem itemLabel=3D"English" itemValue=3D"en"/> + <f:selectItem itemLabel=3D"Deutsch" itemValue=3D"de"/> + <f:selectItem itemLabel=3D"Francais" itemValue=3D"fr"/> +</h:selectOneMenu> +<h:commandButton action=3D"#{localeSelector.select}" value=3D"#{message= s['ChangeLanguage']}"/> + + Or, if you want a list of all supported locales from + faces-config.xml, just use: + + <h:selectOneMenu value=3D"#{localeSe= lector.localeString}"> + <f:selectItems value=3D"#{localeSelector.supportedLocales}"/> +</h:selectOneMenu> +<h:commandButton action=3D"#{localeSelector.select}" value=3D"#{message= s['ChangeLanguage']}"/> + + When this use selects an item from the drop-down, and clicks the + button, the Seam and JSF locales will be overridden for the rest of the + session. +
+ +
+ Labels<anchor id=3D"labels" /> + + JSF supports internationalization of user interface labels and + descriptive text via the use of <f:loadBundle />. + You can use this approach in Seam applications. Alternatively, you can + take advantage of the Seam messages component to + display templated labels with embedded EL expressions. +
- Displaying labels + Defining labels = - - If you define your labels using the Seam resource bundle, you'= ll - be able to use them without having to type <f:load= Bundle ... /> - on every page. Instead, you can simply type: - - = - ]]> - = - - or: - - = - ]]> - = - - Even better, the messages themselves may contain EL expression= s: - + Seam provides a java.util.ResourceBundle + (available to the application as a + org.jboss.seam.core.resourceBundle). You'll need to make y= our + internationalized labels available via this special resource bundle.= By + default, the resource bundle used by Seam is named + messages and so you'll need to define your labels= in + files named messages.properties, + messages_en.properties, + messages_en_AU.properties, etc. These files usually belong= in + the WEB-INF/classes directory. = - - - = - - You can even use the messages in your code: - + So, in messages_en.properties: = - messages;]]> - + Hello=3DHello = + And in messages_en_AU.properties: + + Hello=3DG'day + + You can select a different name for the resource bundle by set= ting + the Seam configuration property named + org.jboss.seam.core.resourceLoader.bundleNames. You can ev= en + specify a list of resource bundle names to be searched (depth first)= for + messages. + + <core:resource-loader> + <core:bundle-names> + <value>mycompany_messages</value> + <value>standard_messages</value> = + </core:bundle-names> +</core:resource-loader> + + If you want to define a message just for a particular page, you + can specify it in a resource bundle with the same name as the JSF vi= ew + id, with the leading / and trailing file extension + removed. So we could put our message in + welcome/hello_en.properties if we only needed to display t= he + message on /welcome/hello.jsp. + + You can even specify an explicit bundle name in + pages.xml: + + <page view-id=3D"/welcome/hello.jsp"= bundle=3D"HelloMessages"/> + + Then we could use messages defined in + HelloMessages.properties on + /welcome/hello.jsp.
- = +
- Faces messages - - The facesMessages component is a super-conv= enient = - way to display success or failure messages to the user. The fu= nctionality = - we just described also works for faces messages: - + Displaying labels = - If you define your labels using the Seam resource bundle, you'= ll + be able to use them without having to type <f:loadBundle + ... /> on every page. Instead, you can simply type: + + <h:outputText value=3D"#{messages[= 'Hello']}"/> + + or: + + <h:outputText value=3D"#{messages.= Hello}"/> + + Even better, the messages themselves may contain EL + expressions: + + Hello=3DHello, #{user.firstName} #{user.lastName} + + Hello=3DG'day, #{user.firstName} + + You can even use the messages in your code: + + @In private Map<String, String> = messages; + + @In("#{messages['Hello']}") private St= ring helloMessage; +
+ +
+ Faces messages + + The facesMessages component is a + super-convenient way to display success or failure messages to the u= ser. + The functionality we just described also works for faces + messages: + + @Name("hello") @Stateless public class HelloBean implements Hello { @In FacesMessages facesMessages; @@ -203,126 +268,110 @@ public String sayIt() { facesMessages.addFromResourceBundle("Hello"); } -}]]> +} = - - This will display Hello, Gavin King or G'day, Gavin, - depending upon the user's locale. - - + This will display Hello, Gavin King or + G'day, Gavin, depending upon the user's + locale.
-
- = -
- Timezones - - There is also a session-scoped instance of java.util.= Timezone, - named org.jboss.seam.international.timezone= , and a Seam component for changing = - the timezone named org.jboss.seam.international.timez= oneSelector. By default, = - the timezone is the default timezone of the server. Unfortunat= ely, the JSF specification = - says that all dates and times should be assumed to be UTC, and= displayed as UTC, unless = - a timezone is explicitly specified using <f:conver= tDateTime>. = - This is an extremely inconvenient default behavior. - - - Seam overrides this behavior, and defaults all dates and times= to the Seam timezone. - In addition, Seam provides the <s:convertDateTime&= gt; tag which = - always performs conversions in the Seam timezone. - -
- = -
- Themes - - Seam applications are also very easily skinnable. The theme AP= I is very - similar to the localization API, but of course these two conce= rns are - orthogonal, and some applications support both localization an= d themes. - - = - - First, configure the set of supported themes: - - = - - - default - accessible - printable - -]]> - = - - Note that the first theme listed is the default theme. - +
= - - Themes are defined in a properties file with the same name as = the theme. - For example, the default theme is defined a= s a set of - entries in default.properties. For example, = - default.properties might define: - - = - +
+ Timezones = - - Usually the entries in a theme resource bundle will be paths t= o CSS styles - or images and names of facelets templates (unlike localization= resource - bundles which are usually text). - - = - - Now we can use these entries in our JSP or facelets pages. For= example, - to theme the stylesheet in a facelets page: - - = - ]]> - = - Or, when the page definition resides in a subdirectory: - = - ]]> - = - - Most powerfully, facelets lets us theme the template used by a= <ui:composition>: - + There is also a session-scoped instance of + java.util.Timezone, named + org.jboss.seam.international.timezone, and a Seam component = for + changing the timezone named + org.jboss.seam.international.timezoneSelector. By default, t= he + timezone is the default timezone of the server. Unfortunately, the JSF + specification says that all dates and times should be assumed to be UT= C, + and displayed as UTC, unless a timezone is explicitly specified using + <f:convertDateTime>. This is an extremely + inconvenient default behavior. = - Seam overrides this behavior, and defaults all dates and times to + the Seam timezone. In addition, Seam provides the + <s:convertDateTime> tag which always performs conversi= ons + in the Seam timezone. +
+ +
+ Themes + + Seam applications are also very easily skinnable. The theme API = is + very similar to the localization API, but of course these two concerns= are + orthogonal, and some applications support both localization and + themes. + + First, configure the set of supported themes: + + <theme:theme-selector cookie-enabled= =3D"true"> + <theme:available-themes> + <value>default</value> + <value>accessible</value> + <value>printable</value> + </theme:available-themes> +</theme:theme-selector> + + Note that the first theme listed is the default theme. + + Themes are defined in a properties file with the same name as the + theme. For example, the default theme is defined as= a + set of entries in default.properties. For example, + default.properties might define: + + css ../screen.css +template /template.xhtml + + Usually the entries in a theme resource bundle will be paths to = CSS + styles or images and names of facelets templates (unlike localization + resource bundles which are usually text). + + Now we can use these entries in our JSP or facelets pages. For + example, to theme the stylesheet in a facelets page: + + <link href=3D"#{theme.css}" rel=3D"s= tylesheet" type=3D"text/css" /> + + Or, when the page definition resides in a subdirectory: + + <link href=3D"#{facesContext.externa= lContext.requestContextPath}#{theme.css}" = + rel=3D"stylesheet" type=3D"text/css" /> + + Most powerfully, facelets lets us theme the template used by a + <ui:composition>: + + <ui:composition xmlns=3D"http://www.= w3.org/1999/xhtml" xmlns:ui=3D"http://java.sun.com/jsf/facelets" xmlns:h=3D"http://java.sun.com/jsf/html" xmlns:f=3D"http://java.sun.com/jsf/core" - template=3D"#{theme.template}">]]> - = - - Just like the locale selector, there is a built-in theme selec= tor to allow = - the user to freely switch themes: - + template=3D"#{theme.template}"> = - - - -]]> + Just like the locale selector, there is a built-in theme selecto= r to + allow the user to freely switch themes: = -
- = -
- Persisting locale and theme preferences via cookies - - The locale selector, theme selector and timezone selector all = support = - persistence of locale and theme preference to a cookie. Simply= set the = - cookie-enabled property in compone= nts.xml: - - = - - - default - accessible - printable - - + <h:selectOneMenu value=3D"#{themeSel= ector.theme}"> + <f:selectItems value=3D"#{themeSelector.themes}"/> +</h:selectOneMenu> +<h:commandButton action=3D"#{themeSelector.select}" value=3D"Select The= me"/> +
= -]]> +
+ Persisting locale and theme preferences via cookies = -
- = - + The locale selector, theme selector and timezone selector all + support persistence of locale and theme preference to a cookie. Simply= set + the cookie-enabled property in + components.xml: + + <theme:theme-selector cookie-enabled= =3D"true"> + <theme:available-themes> + <value>default</value> + <value>accessible</value> + <value>printable</value> + </theme:available-themes> +</theme:theme-selector> + +<international:locale-selector cookie-enabled=3D"true"/> + + \ No newline at end of file --===============3207919548214066926==--