dims 01/05/16 07:42:02
Added: xdocs i18n.xml
Log:
Oops forgot the doc.
Revision Changes Path
1.1 xml-cocoon2/xdocs/i18n.xml
Index: i18n.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>I18n with Cocoon 2</title>
<authors>
<person name="Konstantin Piroumian" email="[EMAIL
PROTECTED]"/>
</authors>
<abstract>
This document describes an aproach for internationalization of
XML
documents within Cocoon 2. It introduces some tags to markup
text
that should be translated and a format for dictionaries.
The first proposal was made by Infozone Group
(http://www.infozone-group.org).
</abstract>
</header>
<body>
<s1 title="Overview">
<s2 title="What is it for?">
<p>
Developing and maintaining multi-language sites
is common problem for web developers.
The usage of XML and XSL makes this task much
more easier, especially with Cocoon's
content, logic and presentation separation
concept.
</p>
<p>
This approach for internationalization (further
- i18n) of XML documents within Cocoon 2
is based on a transformer - <link
href="javadocs/org/apache/cocoon/transformation/I18nTransformer.html">
<code>I18nTransformer</code>
</link>
, it uses XML dictionaries for all the i18n
data. The namespace of i18n is defined as follows:
<code>xmlns:i18n="http://apache.org/cocoon/i18n";</code>
</p>
<p>
First implementation was developed by <link
href="mailto:[EMAIL PROTECTED]">Lassi Immonen</link>. In this implementation
the syntax was changed according to the <link
href="http://www.infozone-group.org";>Infozone Group's</link> i18n proposal
(with a little difference) and new features were implemented.
</p>
</s2>
<s2 title="Features supported">
<p>
Following features are supported by the
i18n transformer:
</p>
<ul>
<li>Text translation</li>
<li>Attribute translation</li>
<li>Param substitution</li>
<li>Substitution param translation</li>
</ul>
<p>
A simple example of i18n:
</p>
<source><![CDATA[
<para title="first" name="article" i18n:attr="title name">
<i18n:text>This text will be translated.</i18n:text>
</para>]]></source>
<p>
Text inside the
<code><![CDATA[<i18n:text>]]></code> will be used as a key to find the
translation in the dictionary. All
attributes that are listed in the <code><![CDATA[<i18n:attr>]]></code>
attribute also will
be translated and their values will be
used as dicionary keys.
</p>
<note>
This i18n approach is not designed to
implement i18n of dates, currencies, etc.
Maybe this features will be supported
in future versions.
</note>
</s2>
</s1>
<s1 title="Markup content for translation">
<s2 title="Simple text translation">
<p>
To translate simple text we use the
<code><![CDATA[<i18n:text>]]></code> tag:
</p>
<source><![CDATA[
<i18n:text>Text to be translated</i18n:text>]]></source>
<p>
The text between the
<code><![CDATA[<i18n:text>]]></code>-tags is used as a key to find the
translation in the dictionary.
</p>
<p>
The 'i18n:key' attribute can be used to specify
a special key for
the dictionary. Normally, the text itself is
used as the key to find
the translation in the dictionary. If we
specify the attribute this
key is used to find the translation and the
text itself is used as the default value,
if translation not found.
</p>
<source><![CDATA[
<i18n:text i18n:key="key_text">Default value</i18n:text>]]></source>
<note>
Maybe it would be better to have a possibility
to use i18n:key in any element and not only in i18n:text.
E.g.:
<code><![CDATA[
<ul>
<li i18n:key="Item1" />
<li i18n:key="Item2" />
...
</ul>
]]></code>
</note>
</s2>
<s2 title="Translation with param susbtitution">
<p>
To translate the text with param substitution
the <code><![CDATA[<i18n:translate>]]></code> tag must be used.
We can specify some
<code><![CDATA[<i18n:param>]]></code>-tags which contain
parameters. The values of these parameters will
be inserted into the
translated text, replacing placeholders.
Placeholders have the
following syntax: <code>\{[0-9]+\}</code>. An
example:
</p>
<source><![CDATA[
<i18n:translate>
<i18n:text>Some {0} was inserted {1}.</i18n:text>
<i18n:param>text</i18n:param>
<i18n:param>here</i18n:param>
</i18n:translate>]]></source>
<p>
Now we want to translate this into German.
First, the processor will look into the dictionary,
we specified, for
the string:
</p>
<p>
<em>Some {0} was inserted {1}.</em>
</p>
<p>
It finds the string and translates it to German:
</p>
<p>
<em>Etwas {0} wurde {1} eingesetzt.</em>
</p>
<p>
Now the processor will replace the parameters. {0}
will be replaced
with "text" and {1} with "here". This results in:
</p>
<p>
<em>Etwas text wurde here
eingesetzt.</em>
</p>
<p>
As we see, it is sometimes necessary to translate
the parameters
as well, since "here" is not a German word and
"text" should be written
uppercase. This can simply be done by marking up
the parameters with
<code><![CDATA[<i18n:text>]]></code> again:
</p>
<source><![CDATA[
<i18n:translate>
<i18n:text>Some {0} was inserted {1}.</i18n:text>
<i18n:param><i18n:text>text</i18n:text></i18n:param>
<i18n:param><i18n:text>here</i18n:text></i18n:param>
</i18n:translate>]]></source>
<note>
Generally, it is not necessary for the text for
param substitution to be translated.
E.g., it can come from a database with
predefined placeholders for i18n params and there is no need to use
<code><![CDATA[<i18n:text>]]></code> for its translation.
</note>
</s2>
<s2 title="Attributes">
<p>
Additionally we can translate
Attributes. This is very useful for
HTML-forms since labels of buttons are
set via an attribute in
HTML. To translate attributes of a tag,
add an additional attribute
named 'i18n:attr' containing a list of
attributes, which should be
translated, separated by spaces. An
example:
</p>
<source><![CDATA[
<INPUT type="submit" value="Submit" i18n:attr="value"/>]]></source>
<p>
The attribute, which will be translated
is 'value'.
Parameter replacement is not available
for attributes at this time.
</p>
</s2>
<s2 title="Dictionaries">
<p>
Dictionaries contain the translations
for the text to be translated.
They consist of a list of entries,
where each entry specifies the
translation(s) for a key. An entry may
contain the translation for
various languages. An example:
</p>
<source><![CDATA[
<translations>
<entry>
<key>Some {0} was inserted {1}.</key>
<translation lang="en">Some {0} was {1} inserted.</translation>
<translation lang="de">Etwas {0} wurde {1}
eingesetzt.</translation>
</entry>
</translations>]]></source>
<p>
For each text, we want to translate, we
must provide a key, where
the key is either text as we've wrote
it in the document or the value
of the 'i18n:key' attribute. The key
must be written exactly like in
the document, including spaces,
linefeeds, etc.
</p>
<p>
Then we must enter a translation for
the text with the <code><![CDATA[<translation>]]></code>-tag,
where the 'lang'-attribute specifies
the language of the translated
text. If the text contains
placeholders, they'll be replaced at the
correct places in the translation with
the given parameters.
</p>
</s2>
<s2 title="How to migrate from the old I18nTransformer">
<p>
Dictionary structure remained the same,
so old dictionaries can be used.
Previous
<code><![CDATA[<i:tr>]]></code> tags are renamed to
<code><![CDATA[<i18n:text>]]></code>. (The namespace prefix is not important,
you can choose any you like).
</p>
<p>
The old transformer supported
translation of any tag using its text value as the key:
</p>
<source><![CDATA[
<elem i18n:tr="y">This text will be translated.</elem>]]>
</source>
<p>
You have to change that for the new
transformer like this:
</p>
<source><![CDATA[
<elem><i18n:text>This text will be translated.</i18n:text></elem>]]>
</source>
<p>
There was a possibility in the old
transformer for choosing image paths depending on the language.
Now you can achieve the same result by
translating the 'src' attribute of img element.
</p>
<note>
I am not sure that image path
translation in the old manner is possible without XSP,
because the language code was used and
not a dictionary.
I'll add a feature for this kind of
translation in the near future.
</note>
</s2>
</s1>
<s1 title="Sample">
<s2 title="Sitemap configuration">
<p>
To use I18nTransformer, it must be
added to the sitemap:
</p>
<source><![CDATA[
<map:transformers default="xslt">
<map:transformer name="i18n"
src="org.apache.cocoon.transformation.I18nTransformer"/>
</map:transformers>]]></source>
<p>
Then, a <code>match</code> must be
declared, something like this:
</p>
<source><![CDATA[
<map:match pattern="file">
<map:generate src="{1}"/>
<map:transform type="i18n">
<parameter name="available_lang_1" value="en"/>
<parameter name="available_lang_2" value="ru"/>
<parameter name="src" value="translations/dictionary.xml"/>
</map:transform>
<map:transform src="stylesheet.xsl"/>
<map:serialize />
</map:match>]]></source>
</s2>
<s2 title="Simple i18n file">
<p>
To use i18n pages you will need to
declare the i18n namespace in your src
files and wrap all i18n text by
<code><![CDATA[<i18n:text>]]></code> tags.
To translate attributes of an element,
add an additional attribute named 'i18n:attr' containing a list of
attributes, which should be translated,
separated by spaces.
</p>
<source><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<root xmlns:i18n="http://apache.org/cocoon/i18n";>
<elem title="main_title" i18n:attr="title">
<i18n:text>Text to be translated</i18n:text>
</elem>
</root>]]></source>
<p>
A more interesting example of usage you
can find in the samples/i18n directory.
</p>
</s2>
<note>
To make attribute translation work the newer
than 1.3.0 version of Xerces is needed, where the removeAttribute()
bug is fixed.
</note>
</s1>
<s1 title="Finally">
<s2 title="What to be done">
<p>
Some more features must be added for
more flexibility and convenience:
</p>
<ul>
<li>Dictionary import and include
capabilities (like in XSLT)</li>
<li>Command line dictionary-from-source
generation</li>
<li>Dictionary caching</li>
</ul>
<p>
Some other features will be considered
for implementation, like: date, currency, floating point numer formats i18n.
</p>
</s2>
<s2 title="Contacts">
<p>
Feel free to contact for any comments
and improvement ideas either directly <link href="mailto:[EMAIL
PROTECTED]">Konstantin Piroumian</link>
or through the <link
href="mail-lists.html">Cocoon Mail List</link>.
</p>
</s2>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
