1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/internationalisation.html Fri Dec 02 23:30:28 2005 +0000
1.3 @@ -0,0 +1,61 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.7 +
1.8 + <title>Internationalisation</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.9 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.10 +<body>
1.11 +<h1>Internationalisation</h1>
1.12 +<p>One important issue was intentionally not covered in the <a href="template-design.html">"Template Design"</a>
1.13 +document: the usage of different texts, labels or phrases chosen
1.14 +according to the languages understood by users of an application. The
1.15 +XSLForms toolkit provides two mechanisms for the use of translations
1.16 +and translated phrases:</p><ul><li>The <a href="reference.html#template:i18n"><code>template:i18n</code></a> attribute, as described in the <a href="reference.html">"Template Attribute Reference"</a> document.</li><li>The <a href="../apidocs/public/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function, as described in the <a href="../apidocs/public/XSLForms.Output-module.html">extension function API documentation</a>.</li></ul><span style="font-family: sans-serif;"><span style="font-weight: bold;"></span></span><p>Each
1.17 +of the above mechanisms has its own specific purpose in template
1.18 +documents, and these purposes are described below, along with the
1.19 +necessary procedures for initialising and invoking the translation
1.20 +mechanisms in an XSLForms application.<br /></p><h2>Translating Element Content</h2><p>Consider the following document fragment:</p><pre><h1>System Configurator</h1></pre><p>In
1.21 +order to translate this to a different language, according to that
1.22 +preferred by the user, we must annotate the element containing the text
1.23 +as follows:</p><pre><h1 template:i18n="-">System Configurator</h1></pre><p>Here, we state that the contents on the <code>h1</code> element (the exact text <code>System Configurator</code>)
1.24 +will be used to find a suitable translation in a translation dictionary
1.25 +(as described below). The anticipated result of applying the annotation
1.26 +would resemble the following output document fragment:</p><pre><h1>Systemkonfigurasjon</h1></pre><p>Consequently,
1.27 +a translation has been inserted in place of the original text. In
1.28 +cases where no translation could be found, the original contents of the
1.29 +element would be preserved.</p><p>It is also possible to employ a
1.30 +specific translation as opposed to the text which just happen to reside
1.31 +inside an element; for example:</p><pre><h1 template:i18n="sysconfig">System Configurator</h1></pre><p>Here, instead of taking the exact text <code>System Configurator</code> as the "token" to be used to find a translation, we instead use the token with the name <code>sysconfig</code>. The effect, providing that the translation of <code>sysconfig</code> is <code>Systemkonfigurasjon</code>, would be the same as the result given above.</p><p>See the <a href="reference.html#template:i18n"><code>template:i18n</code></a> section of the <a href="reference.html">"Template Attribute Reference"</a> document for details of this annotation.</p><h2>Translating Attributes</h2><p>Consider the following document fragment:</p><pre><input type="submit" name="update" value="Update!"/></pre><p>In order to translate the label of this particular form control to another language, we must modify the <code>value</code> attribute as follows:</p><pre><input type="submit" name="update" value="{template:i18n('Update!')}"/></pre><p>Here,
1.32 +we insert an expression inside the attribute whose result will be
1.33 +inserted in place of the expression. Note that for non-template
1.34 +attributes, the expression must reside between <code>{</code> and <code>}</code> characters for the evaluation to take place. The anticipated result might resemble something like the following:</p><pre><input type="submit" name="update" value="Oppdatér"/></pre><p>Where
1.35 +no suitable translation can be found for the text passed to the
1.36 +function, the submitted text is returned as a result, producing
1.37 +something resembling the original, non-translated document fragment.</p><p>See the <a href="../apidocs/public/XSLForms.Output-module.html#i18n"><code>template:i18n</code></a> extension function description in the <a href="../apidocs/public/XSLForms.Output-module.html">extension function API documentation</a> for more details.</p><h2>Initialising and Invoking Translations</h2><p>To
1.38 +permit the translation of text to occur, we must first prepare the
1.39 +translations themselves; then, we must change our application to make
1.40 +use of the translations.</p><h3>Preparing the Translations</h3><p>Translations
1.41 +are typically stored in an XML file alongside other resources such as
1.42 +templates and documents containing data which are also used to prepare
1.43 +the final user-viewable output from an application. For example, one
1.44 +can define a file with the name <code>translations.xml</code> and then insert the following contents into it:</p><pre><?xml version="1.0" encoding="iso-8859-1"?><br /><translations><br /> <locale><br /> <code value="en_GB"/><br /> <code value="en"/><br /> </locale><br /> <locale><br /> <code value="nb_NO"/><br /> <code value="nb"/><br /> <translation value="System Configurator">Systemkonfigurasjon</translation><br /> <translation value="Update!">Oppdatér!</translation><br /> <translation value="Export!">Eksportér!</translation><br /> </locale><br /></translations></pre><p>The structure of any such translations file must resemble the above:</p><ol><li>A top-level <code>translations</code> element containing...</li><li>A number of <code>locale</code> sections, each containing...</li><li>One or more <code>code</code> elements identifying the locale, together with...</li><li>A number of <code>translation</code> elements, each providing a translation for each token.</li></ol><p>In the above example, the locale for <code>en</code> and <code>en_GB</code> have no translations defined; as a result, for any requests for translations in this locale the
1.45 +text already found in the document will be preserved, and this
1.46 +behaviour is therefore equivalent to requests for translations
1.47 +in locales which are not defined or mentioned in the above
1.48 +document.</p><p>Conversely, in the above example, the locale for <code>en</code> and <code>en_GB</code>
1.49 +has some translations defined; as a result, requests for translations
1.50 +in this locale will result in the specified translations being
1.51 +returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the text already found in the document will be preserved.</p><h3>Using the Translations</h3><p>To make use of such a translation file, the file must first be registered in an application. As described in the <a href="Web-resource.html">"Creating Applications: Write a Web Resource"</a> and <a href="XSLForms-resource.html">"Using the XSLFormsResource API"</a> documents, we may add the above example to a resource in the <code>document_resources</code> attribute:</p><pre>document_resources = {<br /> "translations" : "translations.xml"<br /> # Other resources are defined here.<br /> }</pre><p>When
1.52 +producing output for a template which uses internationalisation
1.53 +features, we must first obtain a reference to the above document:</p><pre># In the respond_to_form method of an XSLFormsResource...<br />translations_xml = self.prepare_document("translations")</pre><p>Then,
1.54 +we must decide which language or locale the output will employ. One way
1.55 +of making that decision is to use the WebStack API to find out which
1.56 +languages a user's Web browser is configured to receive:</p><pre># In the respond_to_form method of an XSLFormsResource...<br />languages = trans.get_content_languages()<br /># Get the first one...<br />language = languages[0]</pre><p>Finally,
1.57 +with the above information in hand, we may now modify the output
1.58 +production by adding a document reference (thus permitting the output
1.59 +stylesheet to access the translations document) and by specifying the
1.60 +chosen locale with the <code>locale</code> stylesheet parameter:</p><pre># Use the transaction, output stylesheet, form data document, stylesheet parameters<br /># as well as the document reference.<br />self.send_output(trans, [output_xsl], doc, {"locale" : language},<br /> references={"translations" : translations_xml})</pre><p>This
1.61 +should produce an output document which uses the registered
1.62 +translations as much as is possible for the selected language.
1.63 +Obviously, a more complicated approach could be used to choose the most
1.64 +appropriate language in the <code>languages</code> list, but such algorithms are not covered here.</p></body></html>
1.65 \ No newline at end of file