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