i18n within the XMLForm Framework

This How-To is based on components included in the Cocoon 2.1 distribution. If you don't have this version, you can obtain it from the Apache Cocoon web site.

Some user accessible points in the Cocoon 2.1 distribution should be considered "alpha". This means that the developer team is not investing _any_ effort to provide backward compatibility between alpha releases for these parts. This software will continue to be released as "alpha" until its code, schemas, and APIs are considered stable.

Until then, there will be no warranty that newer versions will maintain backward compatibility for such parts, even in the most simple cases. Of course Cocoon will be compatible to latest release, 2.0.x release. However, once "beta" status is reached, backward incompatible changes will be made only when absolutely necessary to reach "final" status.

The Cocoon development team understands the importance of reliable software as well protecting user investments through the creation of a solid development platform that doesn't change. On the other hand, the Cocoon project is a pioneer in many fields. Most of the technologies it uses are at a "working draft" phase only. Thus, reliability cannot be guaranteed before the software achieves its "final" status.

Until then, no effort will be provided to guarantee backward compatibility for any parts considered alpha.

This How-To shows you how to use the i18n for web site internationalization with the XMLForm Framework. It requires prior knowledge of Cocoon XMLForm, XSLT, Schematron, and i18n.

You will learn how to build a simple Login XMLForm and use i18n to make it multi-language enabled. This How-To teaches you how to build this form. Thus, you will get a better feel for how Cocoon XMLForm really works with i18n.

Cocoon users who want to learn how to use the i18n for web site internationalization with the XMLForm Framework.

Cocoon must be running on your system. The steps below have been tested with Cocoon 2.1-dev.

You will need to understand and be familiar with XSL, i18n, XForms, XPath, and Schematron. If you are unfamiliar with these technologies, it is advised that you learn these related concepts first. If you are unfamiliar with XMLForm, check out the XMLForm Wizard How-To first.

Create the XMLForm login xml file Login.xml and put the <i18n:text> around the form fields as follows:

<?xml version="1.0" ?>
<document xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002"
          xmlns:i18n="http://apache.org/cocoon/i18n/2.0">
  <xf:form id="form-login" view="login" action="do-login" >
    <xf:caption>Login</xf:caption>
    <error>
      <xf:violations class="error"/>
    </error>
  <h5><i18n:text>Login</i18n:text></h5>
   <xf:textbox ref="/email">
       <xf:caption><i18n:text>Email Address</i18n:text></xf:caption>
       <xf:violations class="error"/>
   </xf:textbox>

   <xf:password ref="/password">
       <xf:caption><i18n:text>Password</i18n:text></xf:caption>
       <xf:violations class="error"/>
   </xf:password>
   <xf:submit id="login" class="button">
      <xf:caption><i18n:text>Login</i18n:text></xf:caption>
   </xf:submit>
  </xf:form>
</document>

Create the Schematron validation file general-schema.xml and insert the following validation pattern for the Login XMLForm.

<pattern name="Login Info Validation Pattern" id="login">
  <rule context="/email">
    <assert test="contains( string(.),'@')">
      Email format is invalid.
    </assert>
  </rule>
  <rule context="/password">
    <assert test="string-length(.) &gt; 7">
      The Password Should be @ least 8 characters.
    </assert>
  </rule>
</pattern>

Create a simple XSLT stylesheet file to match the violation element in the XMLForm file, and place it in the sitemap after the XMLForm Transformer. The code of this stylesheet is as follows:

<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xf="http://xml.apache.org/cocoon/xmlform/2002"
    xmlns:i18n="http://apache.org/cocoon/i18n/2.0">

<xsl:template match="document">
     <document>
           <xsl:apply-templates/>
     </document>
</xsl:template>

<xsl:template match="xf:violation">
     <xf:violation>
           <i18n:text>
                 <xsl:value-of select="."/>
           </i18n:text>
     </xf:violation>
</xsl:template>

<xsl:template match="node()" priority="-1">
     <xsl:copy>
           <xsl:copy-of select="@*"/>
           <xsl:apply-templates/>
     </xsl:copy>
</xsl:template>
</xsl:stylesheet>

Basically this snippet is matching the violation element on the form file. If any violations on the entered data occur, it applies the i18n translation on the resulting error messages.

Create the catalog file that contains your error messages and all what you want to be translated. Here is a snippet from the catalog file:

<?xml version="1.0" encoding="UTF-8"?>

<!-- Default English message catalogue file for cocoon2 sample webapp -->

<catalogue xml:lang="en">
  <!-- the Login Form keywords -->
  <message key="Email Address">Email Address</message>
  <message key="Password">Password</message>
  <message key="Login">Login</message>

  <!-- Validation error messages for Login XMLform -->
  <message key="Email format is invalid.">
    Email format is invalid.
  </message>
  <message key="The Password Should be @ least 8 characters.">
    The Password Should be at least 8 characters.
  </message>
</catalogue>

Here is a snippet from a second catalog language file, in this case, for German:

<?xml version="1.0" encoding="UTF-8"?>

<!-- German message catalogue file for cocoon2 sample webapp -->

<catalogue xml:lang="de">
    <!-- the Login Form keywords -->
    <message key="Email Address">Email Adresse</message>
    <message key="Password">Passwort</message>
    <message key="Login">Login</message>

    <!-- Validation error messages for Login Form Xform-->
    <message key="Email format is invalid.">
      Email-format ist ungÃ¼ltig.
    </message>
    <message key="The Password Should be @ least 8 characters.">
      Das Passwort sollte wenigsten 8 Zeichen haben.[translated message]
    </message>
</catalogue>

Now we reach to the end of this How-To by showing the sitemap snippet for this sample:

<map:match pattern="do-login">
  <map:act type="LoginAction">
    <map:parameter name="xmlform-validator-schema-ns" 
      value="http://www.ascc.net/xml/schematron"/>
    <map:parameter name="xmlform-validator-schema" 
      value="xforms/schematron/general-schema.xml"/>
    <map:parameter name="xmlform-id" value="form-login"/>
    <map:parameter name="xmlform-scope" value="session"/>
    <map:parameter name="xmlform-model" 
      value="com.imkenberg.webshop.xforms.LoginBean"/>
    <map:generate src="xforms/xmlforms/login/{page}.xml"/>
    <map:transform type="xmlform" label="xml"/>
    <map:transform src="xforms/stylesheets/translate.xsl"/>
	<map:act type="locale">
      <map:transform type="i18n">
        <map:parameter name="locale" value="{locale}"/>
      </map:transform>
    </map:act>
	<map:transform src="xforms/stylesheets/wizard2html.xsl"/>
	<map:transform src="xforms/stylesheets/xmlform2html.xsl"/>
	<map:act type="locale">
      <map:transform type="i18n">
		<map:parameter name="locale" value="{locale}"/>
      </map:transform>
	</map:act>
  </map:act>
  <map:serialize type="html"/>
</map:match>

This How-To enables you to use i18n Transformer and XMLForm Framework as well as to translate any violation error messages resulting from Shematron validation. I hope you have found this How-To easy to follow.

To go further, you will need to learn about the following technologies and tools.

Care to comment on this How-To? Got another tip? Help keep this How-To relevant by passing along any useful feedback to the author, Mohamed El-Refaey.