1.1 --- a/docs/internationalisation.html Sat Sep 08 16:53:18 2007 +0000
1.2 +++ b/docs/internationalisation.html Sat Sep 08 16:53:34 2007 +0000
1.3 @@ -1,8 +1,8 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.6 <html xmlns="http://www.w3.org/1999/xhtml"><head>
1.7 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 -
1.9 - <title>Internationalisation</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 + <title>Internationalisation</title>
1.11 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.12 <body>
1.13 <h1>Internationalisation</h1>
1.14 @@ -10,28 +10,28 @@
1.15 document: the usage of different texts, labels or phrases chosen
1.16 according to the languages understood by users of an application. The
1.17 XSLForms toolkit provides two mechanisms for the use of translations
1.18 -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
1.19 -of the above mechanisms has its own specific purpose in template
1.20 +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
1.21 +of the above mechanisms has its own specific purpose in template
1.22 documents, and these purposes are described below, along with the
1.23 necessary procedures for initialising and invoking the translation
1.24 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
1.25 order to translate this to a different language, according to that
1.26 preferred by the user, we must annotate the element containing the text
1.27 -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.28 +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.29 will be used to find a suitable translation in a translation dictionary
1.30 (as described below). The anticipated result of applying the annotation
1.31 -would resemble the following output document fragment:</p><pre><h1>Systemkonfigurasjon</h1></pre><p>Consequently,
1.32 -a translation has been inserted in place of the original text. In
1.33 +would resemble the following output document fragment:</p><pre><h1>Systemkonfigurasjon</h1></pre><p>Consequently,
1.34 +a translation has been inserted in place of the original text. In
1.35 cases where no translation could be found, the original contents of the
1.36 element would be preserved.</p><h3>Named Translations</h3><p>It is also possible to employ a
1.37 specific translation as opposed to the text which just happen to reside
1.38 -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><h3>Value Translations</h3><p>In cases where the value being translated is not known before a document is to be displayed, one can either use the <code>template:i18n</code> extension function (as described below), special features of other annotations (such as <code>template:multiple-choice-value</code>), or expression-based translations, where an XPath expression is supplied within the annotation.</p><p>Here is an example for translating a multiple-choice field's values:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:multiple-choice-value="type-enum,type,selected,template:i18n(@type)" value="..."/><br /></select></pre><p>Note that this actually uses the <code>template:i18n</code> extension function in conjunction with the annotation's support for separate labels.</p><p>Here is how this might be done using an expression-based translation:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:i18n="{@type}" template:multiple-choice-value="type-enum,type,selected" value="..."/><br /></select></pre><p>In the above multiple-choice field definition, a range of values are presented that originates from <code>type</code> attributes on a number of <code>type-enum</code>
1.39 +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><h3>Value Translations</h3><p>In cases where the value being translated is not known before a document is to be displayed, one can either use the <code>template:i18n</code> extension function (as described below), special features of other annotations (such as <code>template:multiple-choice-value</code>), or expression-based translations, where an XPath expression is supplied within the annotation.</p><p>Here is an example for translating a multiple-choice field's values:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:multiple-choice-value="type-enum,type,selected,template:i18n(@type)" value="..."/><br /></select></pre><p>Note that this actually uses the <code>template:i18n</code> extension function in conjunction with the annotation's support for separate labels.</p><p>Here is how this might be done using an expression-based translation:</p><pre><select template:multiple-choice-field="-,type" name="..." value="..."><br /> <option template:i18n="{@type}" template:multiple-choice-value="type-enum,type,selected" value="..."/><br /></select></pre><p>In the above multiple-choice field definition, a range of values are presented that originates from <code>type</code> attributes on a number of <code>type-enum</code>
1.40 elements. Instead of just presenting the raw values as the labels for
1.41 the resulting pull-down menu, it is possible to override the
1.42 -underlying <code>template:value</code> mechanism and provide a translation instead.</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,
1.43 +underlying <code>template:value</code> mechanism and provide a translation instead.</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,
1.44 we insert an expression inside the attribute whose result will be
1.45 -inserted in place of the expression. Note that for non-template
1.46 -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.47 +inserted in place of the expression. Note that for non-template
1.48 +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.49 no suitable translation can be found for the text passed to the
1.50 function, the submitted text is returned as a result, producing
1.51 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.52 @@ -41,17 +41,17 @@
1.53 are typically stored in an XML file alongside other resources such as
1.54 templates and documents containing data which are also used to prepare
1.55 the final user-viewable output from an application. For example, one
1.56 -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.57 -text already found in the document will be preserved.</p><p>Conversely, in the above example, the locale for <code>nb</code> and <code>nb_NO</code>
1.58 +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.59 +text already found in the document will be preserved.</p><p>Conversely, in the above example, the locale for <code>nb</code> and <code>nb_NO</code>
1.60 has some translations defined; as a result, requests for translations
1.61 in this locale will result in the specified translations being
1.62 -returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the default translation will be employed.</p><p>Note that the default translation, <strong>in contrast to earlier versions of XSLTools</strong>, is defined by the first <code>locale</code> section.
1.63 +returned, provided the token is defined in a <code>value</code> attribute of a <code>translation</code> element; otherwise, the default translation will be employed.</p><p>Note that the default translation, <strong>in contrast to earlier versions of XSLTools</strong>, is defined by the first <code>locale</code> section.
1.64 Thus, in the above example, other locales not mentioned in the
1.65 -translations file will employ the translations associated with the <code>en</code> and <code>en_GB</code> locales.
1.66 +translations file will employ the translations associated with the <code>en</code> and <code>en_GB</code> locales.
1.67 In this case, the text already found in the document will be preserved
1.68 since no translations are explicitly given for that locale.</p><h4>Summary of Selection Algorithm</h4><p>The following algorithm summarises the above description:</p><ol><li>For a requested locale, look for a matching <code>locale</code> section.</li><li>For a matching section, find a translation for a text value; if a translation is found, return it.</li><li>Where
1.69 no matching section or translation is found, find a translation in the
1.70 -first, default section; if a translation is found, return it.</li><li>Where no matching default translation is found, return the original text value.</li></ol><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
1.71 +first, default section; if a translation is found, return it.</li><li>Where no matching default translation is found, return the original text value.</li></ol><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
1.72 producing output for a template which uses internationalisation
1.73 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.74 we must decide which language or locale the output will employ. One way
1.75 @@ -60,8 +60,8 @@
1.76 with the above information in hand, we may now modify the output
1.77 production by adding a document reference (thus permitting the output
1.78 stylesheet to access the translations document) and by specifying the
1.79 -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.80 +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.81 should produce an output document which uses the registered
1.82 translations as much as is possible for the selected language.
1.83 Obviously, a more complicated approach could be used to choose the most
1.84 -appropriate language in the <code>languages</code> list, but such algorithms are not covered here.</p></body></html>
1.85 \ No newline at end of file
1.86 +appropriate language in the <code>languages</code> list, but such algorithms are not covered here.</p></body></html>