A document has been updated:
http://cocoon.zones.apache.org/daisy/documentation/981.html
Document ID: 981
Branch: main
Language: default
Name: I18nTransformer (unchanged)
Document Type: Sitemap Component (unchanged)
Updated on: 9/11/08 3:05:46 PM
Updated by: David Legg
A new version has been created, state: draft
Parts
=====
Long description
----------------
This part has been added.
Mime type: text/xml
File name: null
Size: 8628 bytes
Content:
<html>
<body>
<p>The Internationalization Transformer <span class="footnote">The term
Internationalization is commonly abbreviated to 'I18N' because it starts with
'I', followed by 18 characters and ends in 'N'. (similarly, Localization is
often abbreviated to 'L10N').</span> is very useful for use in sites supporting
multiple languages. It can be configured to look for special identifiers in
markup and replace them with different text based on a particular locale.</p>
<h2>Overview</h2>
<p>The i18n transformer works by finding a translation for the user's locale in
the configured catalogues. Locale is passed as parameter to the transformer, and
it can be determined based on the request, session, or a cookie by the
org.apache.cocoon.acting.LocaleAction.</p>
<p>For the passed locale it then attempts to find a matching message catalogue
for that locale, and uses it for determining the replacement text directed by
i18n markup.</p>
<p>Message catalogues are maintained in separate files, with a naming convention
similar to that of java.util.ResourceBundle. I.e. basename_locale, where
<em>basename</em> can be any name, and <em>locale</em> can be any locale
specified using ISO 639/3166 characters (eg. en_AU, de_AT, es).</p>
<p class="note">ISO 639 is not a stable standard; some of the language codes it
defines (specifically, iw, ji, and in) have changed (see java.util.Locale for
details).</p>
<h2>Message Catalogues</h2>
<p>Catalogues are in the following format:</p>
<pre><?xml version="1.0"?>
<!-- message catalogue file for locale ... -->
<catalogue xml:lang="locale">
<message key="key">text <i>or</i> markup</message>
....
</catalogue>
</pre>
<p>Where <em>key </em>specifies a particular message for that language.</p>
<h2>Usage</h2>
<p>Files to be translated contain the following markup:</p>
<pre><?xml version="1.0"?>
... some text, translate <i18n:text>key</i18n:text>
</pre>
<p>At runtime, the i18n transformer will find a message catalogue for the user's
locale, and will appropriately replace the text between the <i18n:text>
markup, using the value between the tags as the lookup key.</p>
<p>If the i18n transformer cannot find an appropriate message catalogue for the
user's given locale, it will recursively try to locate a <em>parent</em>
message catalogue, until a valid catalogue can be found. ie:</p>
<ul>
<li>
<strong>catalogue</strong>_<em>language</em>_<em>country</em>_<em>variant</em>.xml
</li>
<li><strong>catalogue</strong>_<em>language</em>_<em>country</em>.xml</li>
<li><strong>catalogue</strong>_<em>language</em>.xml</li>
<li><strong>catalogue</strong>.xml</li>
</ul>
<p>eg: Assuming a basename of <em>messages</em> and a locale of <em>en_AU</em>
(no variant), the following search will occur:</p>
<ul>
<li><strong>messages</strong>_<em>en</em>_<em>AU</em>.xml</li>
<li><strong>messages</strong>_<em>en</em>.xml</li>
<li><strong>messages</strong>.xml</li>
</ul>
<p>This allows the developer to write a hierarchy of message catalogues, at each
defining messages with increasing depth of variation.</p>
<p>In addition, catalogues can be split across multiple locations. For example,
there can be a default catalogue in one directory with a user or client specific
catalogue in another directory. The catalogues will be searched in the order of
the locations specified still following the locale ordering specified above. eg:
Assuming a basename of <em>messages</em> and a locale of <em>en_AU</em> (no
variant) and locations of <em>translations/client</em> and
<em>translations</em>, the following search will occur:</p>
<ul>
<li>
<em>translations/client/</em><strong>messages</strong>_<em>en</em>_<em>AU</em>.xml
</li>
<li><em>translations/</em><strong>messages</strong>_<em>en</em>_<em>AU</em>.xml
</li>
<li><em>translations/client/</em><strong>messages</strong>_<em>en</em>.xml</li>
<li>
<em>translations/</em><strong>messages</strong>_<em>en<em>translations/client/</em><strong>messages</strong>.xml
</em></li>
<li><em><em>translations/</em><strong>messages</strong>.xml </em></li>
</ul>
<p>The i18n:text element can optionally take an attribute i18n:catalogue to
indicate which specific catalogue to use. The value of this attribute should be
the id of the catalogue to use (see sitemap configuration).</p>
<h2>Sitemap Configuration</h2>
<pre><map:transformer name="i18n"
src="org.apache.cocoon.transformation.I18nTransformer">
<catalogues default="someId">
<catalogue id="someId" name="messages" [location="translations"]>
[<location>translations/client</location>]
[<location>translations</location>]
</catalogue>
...
</catalogues>
<untranslated-text>untranslated</untranslated-text>
<preload>en_US</preload>
<preload catalogue="someId">fr_CA</preload>
</map:transformer>
</pre>
<p>Where:</p>
<ul>
<li><strong>catalogues</strong>: (<em>mandatory</em>) container element in which
the catalogues are defined. It must have an attribute 'default' whose value is
one of the id's of the catalogue elements. .</li>
<li><strong>catalogue</strong>: specifies a catalogue. It takes 2 required
attributes: id (can be wathever you like) and name (base name of the catalogue).
The location (location of the message catalogue) is also required, but can be
specified either as an attribute or as one or more subelements, but not both. If
more than one location is specified the catalogues will be searched in the order
they appear in the configuration. The name and location can contain references
to inputmodules (same syntax as in other places in the sitemap). They are
resolved on each usage of the transformer, so they can refer to e.g. request
parameters. (<em>at least 1 catalogue element required</em>). After input module
references are resolved the location string can be the root of a URI. For
example, specifying a location of cocoon:/test with a name of messages and a
locale of en_GB will cause the sitemap to try to process
cocoon:/test/messages_en_GB.xml, cocoon:/test/messages_en.xml and
cocoon:/test/messages.xml.</li>
<li><strong>untranslated-text</strong>: text used for untranslated keys (default
is to output the key name).</li>
<li><strong>preload</strong>: locale of the catalogue to preload. Will attempt
to resolve all configured catalogues for specified locale. If optional catalogue
attribute is present, will preload only specified catalogue. Multiple preload
elements can be specified.</li>
</ul>
<h2>Pipeline Usage</h2>
<p>To use the transformer in a pipeline, simply specify it in a particular
transform, and pass locale parameter:</p>
<pre><map:match pattern="file">
<map:generate src="file.xml"/>
<map:transform type="i18n">
<map:parameter name="locale" value="..."/>
</map:transform>
<map:serialize/>
</map:match>
</pre>
<p>You can use org.apache.cocoon.acting.LocaleAction or any other way to provide
transformer with a locale.</p>
<p>If in certain pipeline, you want to use a different catalogue as the default
catalogue, you can do so by specifying a parameter called
<strong>default-catalogue-id</strong>.</p>
<p>The <strong>untranslated-text</strong> can also be overridden at the pipeline
level by specifying it as a parameter.</p>
<h3>i18n markup</h3>
<p>For date, time and number formatting use the following tags:</p>
<ul>
<li><strong><i18n:date/></strong> gives localized date.</li>
<li><strong><i18n:date-time/></strong> gives localized date and time.</li>
<li><strong><i18n:time/></strong> gives localized time.</li>
<li><strong><i18n:number/></strong> gives localized number.</li>
<li><strong><i18n:currency/></strong> gives localized currency.</li>
<li><strong><i18n:percent/></strong> gives localized percent.</li>
</ul>
<p>Elements date, date-time and time accept pattern and src-pattern attribute,
with values of:</p>
<ul>
<li>short</li>
<li>medium</li>
<li>long</li>
<li>full</li>
</ul>
<p>See java.text.DateFormat for more info on these values.</p>
<p>Elements date, date-time, time and number, a different locale and
source-locale can be specified:</p>
<pre><i18n:date src-pattern="short" src-locale="en_US" locale="de_DE">
12/24/01
</i18n:date>
</pre>
<p>Will result in 24.12.2001.</p>
<p>A given real pattern and src-pattern (not keywords short, medium, long, full)
overrides any value specified by locale and src-locale attributes.</p>
</body>
</html>
