Here are a few examples of XML documents illustrating how ITS can be used with different types of documents. This is not meant to be an exhaustive list of cases.
The ITS-related markup is in bold.
[ Example_01.xml ]
Here the ITS markup is reduced to a minimum, no scope information is
provided as the default value is enough. An application knowing only
its:translate="yes|no"
could process this document properly.
<article xmlns="http://docbook.org/ns/docbook" xmlns:its="http://www.w3.org/2005/11/its" its:translate="yes"> <articleinfo> <title>An example article</title> <author its:translate="no"> <firstname>John</firstname> <surname>Doe</surname> <affiliation> <address><email>foo@example.com</email></address> </affiliation> </author> <copyright its:translate="no"> <year>2000</year> <holder>Gandalf Inc.</holder> </copyright> <abstract> <para>If your article has an abstract then it should go here.</para> </abstract> </articleinfo> <sect1> <title>Title of the first section</title> <para>This is the first section in my article.</para> <sect2> <title>My first sub-section</title> <para>This is the first sub-section in my article.</para> </sect2> </sect1> </article>
[ Example_02.xml ]
Note that the dislocated rules could be in a stand-alone separate document if needed.
<dita:topic xmlns:dita="http://dita.oasis-open.org/architecture/2005/" xmlns:its="http://www.w3.org/2005/11/its" DITAArchVersion="1.0" id="myTopic"> <dita:title>Some little topic</dita:title> <its:documentRules> <its:documentRule its:translateScope="//*[@dita:translate='yes']" its:translate="yes" /> <its:documentRule its:translateScope="//*[@dita:translate='no']" its:translate="no" /> <its:documentRule its:termScope="//dita:term" its:term="yes" /> <its:documentRule its:termScope="//dita:dt" its:term="yes" /> </its:documentRules> <dita:body> <dita:p>Here are some ITS definitions:</dita:p> <dita:dl> <dita:dlentry id="tDataCat"> <dita:dt>Data category</dita:dt> <dita:dd>ITS defines <dita:term>data category</dita:term> as an abstract concept for a particular type of information for internationalization and localization of XML schemas and documents.</dita:dd> </dita:dlentry> <dita:dlentry id="tScope"> <dita:dt>Scope</dita:dt> <dita:dd>Scope is a means to describe to what elements and/or attributes an ITS <dita:term>data category</dita:term> and its values should be applied to.</dita:dd> </dita:dlentry> </dita:dl> <dita:p>As for the implementation of ITS: just apply the rules in the order:</dita:p> <dita:ul> <dita:li>Default</dita:li> <dita:li>Rules in the schema</dita:li> <dita:li>Dislocated rules</dita:li> <dita:li>in situ rules</dita:li> </dita:ul> <dita:p><dita:ph translate="no" xml:lang="fr">Et voila !</dita:ph> The last rule wins</dita:p> </dita:body> </dita:topic>
There is no in situ ITS markup in this DITA document since no rule was needed to override either the dislocated rules, or the default rules. The document is compatible with applications knowledgeable of DITA only, and applications knowledgeable of ITS only. All the DITA translatability or terminology information (indicated in bold and blue) is also caught by the applications knowledgeable of ITS only through the dislocated rules which act here as a mapping mechanism).
If the dislocated rules are in a standalone document, no ITS markup at all is needed in the DITA document, as shown below:
<its:documentRules xmlns:its="http://www.w3.org/2005/11/its"> <its:documentRule its:translateScope="//*[@translate='yes']" its:translate="yes" /> <its:documentRule its:translateScope="//*[@translate='no']" its:translate="no" /> <its:documentRule its:termScope="//term" its:term="yes" /> <its:documentRule its:termScope="//dt" its:term="yes" /> </its:documentRules>
<topic DITAArchVersion="1.0" id="myTopic"> <title>Some little topic</title> <body> <p>Here are some ITS definitions:</p> <dl> <dlentry id="tDataCat"> <dt>Data category</dt> <dd>ITS defines <term>data category</term> as an abstract concept for a particular type of information for internationalization and localization of XML schemas and documents.</dd> </dlentry> <dlentry id="tScope"> <dt>Scope</dt> <dd>Scope is a means to describe to what elements and/or attributes an ITS <term>data category</term> and its values should be applied to.</dd> </dlentry> </dl> <p>As for the implementation of ITS: just apply the rules in the order:</p> <ul> <li>Default</li> <li>Rules in the schema</li> <li>Dislocated rules</li> <li>in situ rules</li> </ul> <p><ph translate="no" xml:lang="fr">Et voila !</ph> The last rule wins</p> </body> </topic>
[ Example_03.xml ]
The default values for translatability are yes for the element and no for the attribute. Here the dislocated rules provide overrides for the defaults:
desc
attributes in a <pict>
element should generally be translated,<head>
element should be
translated.In addition, a few in situ indicators are also present, overriding defaults and dislocated rules:
<q>
element should not be
translated (overrides the default),desc
attribute in the second <pict>
element should not be translated (overrides the dislocated rules).<myDoc xmlns="myDocURI" xmlns:its="http://www.w3.org/2005/11/its"> <body> <para id="p1">The motto of Québec is the short phrase: <q its:translate="no" xml:lang="fr-ca">Je me souviens</q>. It is chiseled on the front of the Parliament Building: <pict ref="Motto.jpg" desc="Je me souviens" its:translate="no" its:translateScope="./@desc" /></para> <para id="p2">As for the coat of arms, it looks like this: <pict ref="CoA.png" desc="Québec's Coat of Arms" /></para> </body> <docInfo> <its:documentRules> <its:documentRule translateScope="//head" translate="no" /> <its:documentRule translateScope="//pict@desc" translate="yes" /> </its:documentRules> <author>Jane Doe</author> <lastChange>2006-01-13</lastChange> </docInfo> </myDoc>
Note that the precedence order between dislocated rules and in situ
rules are not related to their position in the document. In this example
the <its:documentRules>
element is placed at the end of the
document to illustrate this. It could be anywhere and the result would
be the same.
Note also that using an attribute (desc
) to hold
translatable text is a bad practice, and used here only for illustration
purpose.
There are more examples here.