You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by di...@apache.org on 2001/05/16 16:42:02 UTC
cvs commit: xml-cocoon2/xdocs i18n.xml
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="kot_p@hotbox.ru"/>
</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:lassi.immonen@valkeus.com">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:kpiroumian@flagship.ru">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: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org