tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Tapestry > Localization
Date Wed, 16 Jun 2010 12:11:00 GMT
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/8/_/styles/combined.css?spaceKey=TAPESTRY&amp;forWysiwyg=true"
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Localization">Localization</a></h2>
    <h4>Page  <b>added</b> by             <a href="https://cwiki.apache.org/confluence/display/~uli">Ulrich
    <div class="notificationGreySide">
         <h1><a name="Localization-Localization"></a>Localization</h1>

<p>Localization is all about getting the right text to the user, in the right language.</p>

<p>Localization support is well integrated into Tapestry. Tapestry allows you to easily
separate the text you present to your users from the rest of your application ... pull it
out of your Java code and even out of your component templates. You can then translate your
messages into other languages and let Tapestry put everthing together.</p>

<h1><a name="Localization-ComponentMessageCatalogs"></a>Component Message

<p>Each component class may have a component message catalog. A component message catalog
is a set of files with the extension ".properties". These property files are the same format
used by java.util.ResourceBundle, just lines of <tt>key=value</tt>. These files
are stored on the classpath, in the same package folder as the page or component's compiled
Java class.</p>

<p>So for a class named org.example.myapp.pages.MyPage, you would have a main properties
file as <tt>org/example/myapp/pages/MyPage.properties</tt>.</p>

<p>If you have a translations of these values, you provide additional properties file,
adding an <a href="http://www.loc.gov/standards/iso639-2/englangn.html" class="external-link"
rel="nofollow">ISO language code</a> before the extension. Thus, if you have a French
translation, you could create a file <tt>MyPage_fr.properties</tt>.</p>

<p>Any values in the more language specific file will <em>override</em>
values from the main properties file. If you had an even more specific localization for just
French as spoken in France, you could create <tt>MyPage_fr_FR.properties</tt>
(thats a language code plus a country code, you can even go further and add variants ... but
its unlikely that you'll ever need to go beyond just language codes in practice).</p>

<p>The messages in the catalog are accessed by keys. Tapestry ignores the case of the
keys when accessing messages in the catalog.</p>

<h1><a name="Localization-PropertiesFileCharset"></a>Properties File Charset</h1>

<p>Tapestry uses the <tt>UTF-8</tt> charset when reading the properties
files in a message catalog. This means that you don't have to use the Java <tt>native2ascii</tt>

<h1><a name="Localization-MessageCatalogInheritance"></a>Message Catalog

<p>If a component class is a subclass of another component class, then it inherits that
base class' message catalog. Its own message catalog extends and overrides the values inherited
from the base class.</p>

<p>In this way, you could have a base component class that contained common messages,
and extend or override those messages in subclasses (just as you would extend or override
the methods of the base component class). This, of course, works for as many levels of inheritance
as you care to support.</p>

<h1><a name="Localization-ApplicationMessageCatalog"></a>Application Message

<p>If the file <tt>WEB-INF/</tt><em>AppName</em><tt>.properties</tt>
exists in the context, it will be used as an application-wide message catalog. The <em>AppName</em>
is derived from the name of the filter inside the web.xml file; this is most often just "app",
thus <tt>WEB-INF/app.properties</tt>. The search for the file is case sensitive.
The properties files may be localized.</p>

<p>Individual pages and components can override the values defined in the message catalog.</p>

<h1><a name="Localization-LocalizedComponentTemplates"></a>Localized Component

<p>The same lookup mechanism applies to component templates. Tapestry will search for
a localized version of each component template and use the closest match. Thus you could have
<tt>MyPage_fr.html</tt> for French users, and <tt>MyPage.html</tt>
for all other users.</p>

<h1><a name="Localization-AccessingLocalizedMessages"></a>Accessing Localized

<p>The above discusses what files to create and where to store them, but doesn't address
how to make use of that information.</p>

<p>Messages can be accessed in one of two ways:</p>

	<li>Using the <a href="#Localization-parameters.html">message: binding prefix</a>
in a component template</li>
	<li>By injecting the component's Messages object<br/>
In the first case, you may use the message: binding prefix with component parameters, or with
template expansions:</li>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;t:layout title=<span class="code-quote">"message:page-title"</span>&gt;

  ${message:greeting}, ${user.name}!
  . . .

<p>Here, the <tt>page-title</tt> message is extracted from the catalog and
passed to the Border component's title parameter.</p>

<p>In addition, the <tt>greeting</tt> message is extracted and written into
the response as part of the template.</p>

<p>As usual, "prop:" is the defalt binding prefix, thus <tt>user.name</tt>
is a property path, not a message key.</p>

<p>You would extend this with a set of properties files:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
page-title=Your Account
greeting=Welcome back

<p>Or, perhaps, a French version:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
page-title=Votre Compte
greeting=Bienvenue en arriere

<p>Programatically, you may inject your component message catalog into your class, as
an instance of the Messages interface:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  <span class="code-keyword">private</span> Messages messages;

<p>You could then <tt>get()</tt> messages, or <tt>format()</tt>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">

  <span class="code-keyword">public</span> <span class="code-object">String</span>
    <span class="code-keyword">if</span> (items.isEmpty())
      <span class="code-keyword">return</span> messages.get(<span class="code-quote">"no-items"</span>);
    <span class="code-keyword">return</span> messages.format(<span class="code-quote">"item-summary"</span>,

<p>The format() option works using a java.text.Formatter, with all the printf-style
loveliness you've come to expect:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
no-items=Your shopping cart is empty.     
item-summary=You have %d items in your cart.

<p>As easy as conditionals are to do inside a Tapestry template, sometimes its even
easier to do it in Java code.</p>

<h1><a name="Localization-MissingKeys"></a>Missing Keys</h1>

<p>If you reference a key that is not in the message catalog, Tapestry does not throw
an exception (that would make initially developing an application very frustrating). When
a key can not be located, a "placeholder" message is generated, such as "[<span class="error">&#91;missing
key: key\-not\-found&#93;</span>]".</p>

<h1><a name="Localization-Reloading"></a>Reloading</h1>

<p>If you change a property file in a message catalog, you'll see the change immediately,
just as with component classes and component templates.</p>

<h1><a name="Localization-AssetLocalization"></a>Asset Localization</h1>

<p>When <a href="#Localization-inject.html">injecting assets</a>, the injected
asset will be localized as well. A search for the closest match for the active locale is made,
and the final Asset will reflect that.</p>

<h1><a name="Localization-LocaleSelection"></a>Locale Selection</h1>

<p>The locale for each request is determined from the HTTP request headers. The request
locale reflects the environment of the web browser and possibly even the keyboard selection
of the user on the client. It can be highly specific, for example, identifying British English
(as en_GB) vs. American English (en).</p>

<p>Tapestry "narrows" the raw request locale, as specified in the request, to a known
quantity. It uses the <a href="#Localization-conf.html">configuration symbol</a>
tapestry.supported-locales to choose the effective locale for each request. This value is
a comma-separated list of locale names. Tapestry searches the list for the best match for
the request locale; for example, a request locale of "fr_FR" would match "fr" but not "de".
If no match is found, then the first locale name in the list is used as the effective locale
(that is, the first locale is used as the default for non-matching requests). Thus a site
that primarily caters to French speakers would want to list "fr" as the first locale in the

<h1><a name="Localization-ChangingtheLocale"></a>Changing the Locale</h1>

<p>The service <span class="error">&#91;PersistentLocale|../apidocs/org/apache/tapestry5/PersistentLocale.html&#93;</span>
is used to programmatically override the locale for the current request.</p>

<p>Once a persistent locale is set, you will see the locale name as the first virtual
folder in page render and component event requests URLs. In this way, a persistent locale
will, in fact, persist from request to request, or in a user's bookmarks.</p>

<p>You should be careful to only set the persistent locale to a supported locale.</p>

<p>You will see the new locale take effect on the next request. If it is changed in
a component event request (which is typical), the new locale will be used in the subsequent
page render request.</p>

<p>Note that the locale for a page is fixed (it can't change once the page instance
is created). In addition, a page may only be attached to a request once. In other words, if
code in your page changes the persistent locale, you won't see a change to the page's locale
(or localized messages) <em>in that request</em>.</p>

<h1><a name="Localization-OutputContentTypeandCharset"></a>Output Content
Type and Charset</h1>

<p>When Tapestry renders a page, the very first step is to determine the output content
type and charset.</p>

<p>This information is obtained from meta data on the page itself. Meta data is specified
using the <span class="error">&#91;Meta|../apidocs/org/apache/tapestry5/annotations/Meta.html&#93;</span>

<p>The response content type is obtained via meta-data key "tapestry.response-content-type".
This value defaults to "text/html".</p>

<p>As a convienence, the <span class="error">&#91;ContentType|../apidocs/org/apache/tapestry5/annotations/ContentType.html&#93;</span>
annotation can be used to specify the response content type. The value attribute of the annotation
is the content type.</p>

<p>The character set for all outgoing markup and all incoming requests is "UTF-8". UTF-8
is a version of Unicode where individual characters are encoded as one or more bytes. Most
western language characters (that is, typical ASCII characters) are encoded in a single byte.
Accented characters or non-western characters (such as Japanese, Arabic, etc.) may be encoded
as two or more bytes.</p>

    <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       <a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Localization">View

View raw message