1.1 --- a/docs/internationalisation.html Thu Jan 18 23:33:37 2007 +0000
1.2 +++ b/docs/internationalisation.html Thu Jan 18 23:34:11 2007 +0000
1.3 @@ -42,13 +42,16 @@
1.4 templates and documents containing data which are also used to prepare
1.5 the final user-viewable output from an application. For example, one
1.6 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.7 -text already found in the document will be preserved, and this
1.8 -behaviour is therefore equivalent to requests for translations
1.9 -in locales which are not defined or mentioned in the above
1.10 -document.</p><p>Conversely, in the above example, the locale for <code>en</code> and <code>en_GB</code>
1.11 +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.12 has some translations defined; as a result, requests for translations
1.13 in this locale will result in the specified translations being
1.14 -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.15 +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.16 +Thus, in the above example, other locales not mentioned in the
1.17 +translations file will employ the translations associated with the <code>en</code> and <code>en_GB</code> locales.
1.18 +In this case, the text already found in the document will be preserved
1.19 +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.20 +no matching section or translation is found, find a translation in the
1.21 +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.22 producing output for a template which uses internationalisation
1.23 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.24 we must decide which language or locale the output will employ. One way