1.1 --- a/docs/internationalisation.html Sat Dec 03 01:52:11 2005 +0000
1.2 +++ b/docs/internationalisation.html Sat Dec 03 01:53:18 2005 +0000
1.3 @@ -10,11 +10,11 @@
1.4 document: the usage of different texts, labels or phrases chosen
1.5 according to the languages understood by users of an application. The
1.6 XSLForms toolkit provides two mechanisms for the use of translations
1.7 -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.8 +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.9 of the above mechanisms has its own specific purpose in template
1.10 documents, and these purposes are described below, along with the
1.11 necessary procedures for initialising and invoking the translation
1.12 -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.13 +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.14 order to translate this to a different language, according to that
1.15 preferred by the user, we must annotate the element containing the text
1.16 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.17 @@ -25,7 +25,7 @@
1.18 cases where no translation could be found, the original contents of the
1.19 element would be preserved.</p><p>It is also possible to employ a
1.20 specific translation as opposed to the text which just happen to reside
1.21 -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.22 +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,
1.23 we insert an expression inside the attribute whose result will be
1.24 inserted in place of the expression. Note that for non-template
1.25 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.26 @@ -34,7 +34,7 @@
1.27 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.28 permit the translation of text to occur, we must first prepare the
1.29 translations themselves; then, we must change our application to make
1.30 -use of the translations.</p><h3>Preparing the Translations</h3><p>Translations
1.31 +use of the translations.</p><h3><a name="PreparingTheTranslations"></a>Preparing the Translations</h3><p>Translations
1.32 are typically stored in an XML file alongside other resources such as
1.33 templates and documents containing data which are also used to prepare
1.34 the final user-viewable output from an application. For example, one
1.35 @@ -45,7 +45,7 @@
1.36 document.</p><p>Conversely, in the above example, the locale for <code>en</code> and <code>en_GB</code>
1.37 has some translations defined; as a result, requests for translations
1.38 in this locale will result in the specified translations being
1.39 -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.40 +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
1.41 producing output for a template which uses internationalisation
1.42 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.43 we must decide which language or locale the output will employ. One way