1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"><head> 3 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 4 5 <title>Internationalisation</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 6 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 7 <body> 8 <h1>Internationalisation</h1> 9 <p>One important issue was intentionally not covered in the <a href="template-design.html">"Template Design"</a> 10 document: the usage of different texts, labels or phrases chosen 11 according to the languages understood by users of an application. The 12 XSLForms toolkit provides two mechanisms for the use of translations 13 and translated phrases:</p><ul><li>The <a href="reference.html#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 14 of the above mechanisms has its own specific purpose in template 15 documents, and these purposes are described below, along with the 16 necessary procedures for initialising and invoking the translation 17 mechanisms in an XSLForms application.<br /></p><h2><a name="TranslatingElementContent"></a>Translating Element Content</h2><p>Consider the following document fragment:</p><pre><h1>System Configurator</h1></pre><p>In 18 order to translate this to a different language, according to that 19 preferred by the user, we must annotate the element containing the text 20 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>) 21 will be used to find a suitable translation in a translation dictionary 22 (as described below). The anticipated result of applying the annotation 23 would resemble the following output document fragment:</p><pre><h1>Systemkonfigurasjon</h1></pre><p>Consequently, 24 a translation has been inserted in place of the original text. In 25 cases where no translation could be found, the original contents of the 26 element would be preserved.</p><p>It is also possible to employ a 27 specific translation as opposed to the text which just happen to reside 28 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#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><a name="TranslatingAttributes"></a>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, 29 we insert an expression inside the attribute whose result will be 30 inserted in place of the expression. Note that for non-template 31 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 32 no suitable translation can be found for the text passed to the 33 function, the submitted text is returned as a result, producing 34 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 35 permit the translation of text to occur, we must first prepare the 36 translations themselves; then, we must change our application to make 37 use of the translations.</p><h3><a name="PreparingTheTranslations"></a>Preparing the Translations</h3><p>Translations 38 are typically stored in an XML file alongside other resources such as 39 templates and documents containing data which are also used to prepare 40 the final user-viewable output from an application. For example, one 41 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 42 text already found in the document will be preserved, and this 43 behaviour is therefore equivalent to requests for translations 44 in locales which are not defined or mentioned in the above 45 document.</p><p>Conversely, in the above example, the locale for <code>en</code> and <code>en_GB</code> 46 has some translations defined; as a result, requests for translations 47 in this locale will result in the specified translations being 48 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><a name="UsingTheTranslations"></a>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 49 producing output for a template which uses internationalisation 50 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, 51 we must decide which language or locale the output will employ. One way 52 of making that decision is to use the WebStack API to find out which 53 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, 54 with the above information in hand, we may now modify the output 55 production by adding a document reference (thus permitting the output 56 stylesheet to access the translations document) and by specifying the 57 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 58 should produce an output document which uses the registered 59 translations as much as is possible for the selected language. 60 Obviously, a more complicated approach could be used to choose the most 61 appropriate language in the <code>languages</code> list, but such algorithms are not covered here.</p></body></html>