How to use the I18NTransformer for Internationalization

The I18N Internationalization Transformer is similar to tha of the Cocoon transformer but it does not contin the same functionality as the latter, for example parametered text does not exist in Paloose. The following describes the Paloose version.

Sitemap

The root sitemap needs to have the Gallery Transformer declared as a component:

<map:transformers default="xslt"> ... <map:transformer name="i18n" src="resource://lib/transforming/I18nTransformer"> <map:catalogues default="index"> <map:catalogue id="index" name="index" location="context://content/translations"/> ... </map:catalogues> <map:untranslated-text>untranslated text</map:untranslated-text> </map:transformer> ... </map:transformers>

where

name — the name of this selector (in this case i18n).
src — the location of the PHP package for this component.

There is a sub-element, <map:catalogues>, that defines the the catalogue (translation) files. In this case a single catalogue file is shown, where

id — the id of the catalogue file and its various language files.
name — the name of the catalogue series (they take the form index_xx.xml, where xx is the language code).
location — the location of the translation files for this catalogue.

The other sub-element, <map:untranslated>, defines the text to be output when the appropriate translation cannot be found. We can use the transformer anywhere in the pipeline that any other transformer can be and can have label views associated with it. For example (from this site):

<map:match pattern="**.xml"> <map:generate src="cocoon:/{1}.xml" label="xml-content"/> <map:transform type="i18n" label="i18n-transform"> <map:parameter name="default-catalogue-id" value="i18n-id" /> </map:transform> <map:serialize/> </map:match>

Building the Catalogue Files

For each language that you require a catalogue file must be written. The format for this file is very simple, for example:

<?xml version="1.0" encoding="UTF-8"?> <catalogue xmlns:link="http://www.hsfr.org.uk/Schema/Link" xml:lang="de"> <message key="one">ein</message> <message key="two">zwei</message> <message key="three">drei</message> </catalogue>

It is effectively a list of messages accessed by key, where

key — the key that is used in the content text to refer to the message.
tag content — the translated text to be used to substitue in the content text.

Building the Text File

In order to use the transformer there are several tags that indicate what text should be translated.

i18n:text

The primary one is <i18n:text> which can be used in two ways. Note that Paloose support multiple dictionaries declared in the <i18n:text> or parameter substitution yet.

Using the content text as the key. Using the above catalogue file example we could say
<t:p><i18n:text>one</i18n:text></t:p>
which would translate to
<t:p>ein</t:p>
Using an explicit key. Again uUsing the above catalogue file example we could say
<t:p><i18n:text key="one"/></t:p>
which would translate to the same XML. It is possible to put in some content which would be output if the locale is not defined. For example
<t:p><i18n:text key="one">one (1)</i18n:text></t:p>
which would translate to
<t:p>one (1)</t:p>
if there was no locale given.

Attributes

As well as tag content it is possible to translate attributes within tags. For example if have

The name attribute's value would be translated.

Date and Time Formatting

The date and time formatting is one area that is different to Cocoon in how it deals with the pattern format. Take the two date and time tags which will output the current date and time:

<t:p> <i18n:date pattern="%A, %e %B %G"/> </t:p> <t:p> <i18n:time pattern="%X (%Z)"/> </t:p>

The pattern attribute uses PHP pattern format character (see PHP manual for a full list).

If a value attribute is given then the date/time is taken from that. Note that there is no src-pattern attribute to define the format of the value, Paloose uses the PHP parser as best it can to discover the date/time.

Number Formatting

Currently there is no facility for number formatting — I will add this when I find I need it.