Internationalization Tag Set (ITS) Version 1.0

1.1.1 Typical Problems

The following examples sketch one of the issues that currently hinder efficient XML-related localization: the lack of a standard, declarative mechanism which identifies which parts of an XML document need to be translated. Tools often cannot automatically do this identification.

<resources>
 <section id="Homepage">
  <arguments>
   <string>page</string>
   <string>childlist</string>
  </arguments>
  <variables>
   <string>POLICY</string>
   <string>Corporate Policy</string>
  </variables>
  <keyvalue_pairs>
   <string>Page</string>
   <string>ABC Corporation - Policy Repository</string>
   <string>Footer_Last</string>
   <string>Pages</string>
   <string>bgColor</string>
   <string>NavajoWhite</string>
   <string>title</string>
   <string>List of Available Policies</string>
  </keyvalue_pairs>
 </section>
</resources>

<dialogue xml:lang="en-gb">
 <rsrc id="123">
  <component id="456" type="image">
   <data type="text">images/cancel.gif</data>
   <data type="coordinates">12,20,50,14</data>
  </component>
  <component id="789" type="caption">
   <data type="text">Cancel</data>
   <data type="coordinates">12,34,50,14</data>
  </component>
  <component id="792" type="string">
   <data type="text">Number of files: </data>
  </component>
 </rsrc>
</dialogue>

1.2.1 Potential Users of ITS

The ITS specification aims to provide different types of users with information about what markup should be supported to enable worldwide use and effective internationalization and localization of content. The following paragraphs sketch these different types of users, and their usage of ITS.

• Schema developers who start a schema from ground up

  This type of user will find proposals for attribute and element names to be included in their new schema (also called "host vocabulary"). Using the attribute and element names proposed in the ITS specification may be helpful because it leads to easier recognition of the concepts represented by both schema users and processors. It is perfectly possible, however, for a schema developer to develop his own set of attribute and element names. The specification sets out, first and foremost, to ensure that the required markup is available, and that the behavior of that markup meets established needs.

• Schema developers who work with an existing schema

  This type of user will be working with schemas such as DocBook, DITA, or perhaps a proprietary schema. The ITS Working Group has sought input from experts developing widely used formats such as the ones mentioned.

  Note:

  The question "How to use ITS with existing popular markup schemes?" is covered in more details (including examples) in a separate document: [XML i18n BP].

  Developers working on existing schemas should check whether their schemas support the markup proposed in this specification, and, where appropriate, add the markup proposed here to their schema.

  In some cases, an existing schema may already contain markup equivalent to that recommended in ITS. In this case it is not necessary to add duplicate markup since ITS provides mechanisms for associating ITS markup with markup in the host vocabulary which serves a similar purpose (see Section 5.5: Associating ITS Data Categories with Existing Markup). The developer should, however, check that the behavior associated with the markup in their own schema is fully compatible with the expectations described in this specification.

• Vendors of content-related tools

  This type of user includes companies which provide tools for authoring, translation or other flavors of content-related software solutions. It is important to ensure that such tools enable worldwide use and effective localization of content. For example, translation tools should prevent content marked up as not for translation from being changed or translated. It is hoped that the ITS specification will make the job of vendors easier by standardizing the format and processing expectations of certain relevant markup items, and allowing them to more effectively identify how content should be handled.

• Content producers

  This type of user comprises authors, translators and other types of content author. The markup proposed in this specification may be used by them to mark up specific bits of content. Aside: The burden of inserting markup can be removed from content producers by relating the ITS information to relevant bits of content in a global manner (see global, rule-based approach). This global work, however, may fall to information architects, rather than the content producers themselves.

In order to support all of these users, the information about what markup should be supported to enable worldwide use and effective localization of content is provided in this specification in two ways:

• abstractly in the data category descriptions: Section 6: Description of Data Categories

• concretely in the ITS schemas: Appendix D: Schemas for ITS

1.2.2 Ways to Use ITS

The ITS specification proposes several mechanisms for supporting worldwide use and effective internationalization and localization of content. We will sketch them below by looking at them from the perspectives of certain user types. For the purpose of illustration, we will demonstrate how ITS can indicate that certain parts of content should or should not be translated.

• A content author uses an attribute on a particular element to say that the text in the element should not be translated.

<help
  xmlns:its="http://www.w3.org/2005/11/its" 
  its:version="1.0">
 <head>
  <title>Building the Zebulon Toolkit</title>
 </head>
 <body>
  <p>To re-compile all the modules of the Zebulon toolkit you need to go in the
    <path
     its:translate="no">\Zebulon\Current Source\binary</path> directory.
    Then from there, run batch file <cmd
     its:translate="no">Build.bat</cmd>.</p>
 </body>
</help>

• A content author or information architect uses markup at the top of the document to identify a particular type of element or context in which the content should not be translated.

<help
  xmlns:its="http://www.w3.org/2005/11/its" 
  its:version="1.0">
 <head>
  <title>Building the Zebulon Toolkit</title>
  <its:rules version="1.0">
   <its:translateRule selector="//path | //cmd" translate="no"/>
  </its:rules>
 </head>
 <body>
  <p>To re-compile all the modules of the Zebulon toolkit you need to go in the
    <path>\Zebulon\Current Source\binary</path> directory.
    Then from there, run batch file <cmd>Build.bat</cmd>.</p>
 </body>
</help>

• A processor may insert markup at the top of the document which links to ITS information outside of the document.

<help
  xmlns:its="http://www.w3.org/2005/11/its" 
  xmlns:xlink="http://www.w3.org/1999/xlink" 
  its:version="1.0">
 <head>
  <title>Building the Zebulon Toolkit</title>
  <its:rules version="1.0" xlink:href="EX-ways-to-use-its-4.xml" xlink:type="simple"/>
 </head>
 <body>
  <p>To re-compile all the modules of the Zebulon toolkit you need to go in the
    <path>\Zebulon\Current Source\binary</path> directory.
    Then from there, run batch file <cmd>Build.bat</cmd>.</p>
 </body>
</help>

<its:rules
  xmlns:its="http://www.w3.org/2005/11/its"  version="1.0">
 <its:translateRule selector="//path | //cmd" translate="no"/>
</its:rules>

• A schema developer integrates ITS markup declarations in his schema to allow users to indicate that specific parts of the content should not be translated.

<xs:schema
  xmlns:its="http://www.w3.org/2005/11/its" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema"  elementFormDefault="qualified">
 <xs:import namespace="http://www.w3.org/2005/11/its" schemaLocation="its.xsd"/>
 <xs:attributeGroup name="commonAtts">
  <xs:attributeGroup ref="its:att.local.with-ns.attribute.translate"/>
  <xs:attribute name="id" type="xs:ID" use="optional"/>
 </xs:attributeGroup>
 <xs:element name="help">
  <xs:complexType>
   <xs:sequence>
    <xs:element name="head">
     <xs:complexType>
      <xs:sequence>
       <xs:element name="title" type="xs:string"/>
      </xs:sequence>
      <xs:attributeGroup ref="commonAtts"/>
     </xs:complexType>
    </xs:element>
    <xs:element name="body">
     <xs:complexType>
      <xs:choice minOccurs="1" maxOccurs="unbounded">
       <xs:element name="p">
        <xs:complexType mixed="true">
         <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:element ref="path"/>
          <xs:element ref="cmd"/>
         </xs:choice>
         <xs:attributeGroup ref="commonAtts"/>
        </xs:complexType>
       </xs:element>
      </xs:choice>
     </xs:complexType>
    </xs:element>
   </xs:sequence>
   <xs:attributeGroup ref="its:att.version.attribute.version"/>
  </xs:complexType>
 </xs:element>
 <xs:element name="path">
  <xs:complexType mixed="true">
   <xs:attributeGroup ref="commonAtts"/>
  </xs:complexType>
 </xs:element>
 <xs:element name="cmd">
  <xs:complexType mixed="true">
   <xs:attributeGroup ref="commonAtts"/>
  </xs:complexType>
 </xs:element>
</xs:schema>

The first two approaches above can be likened to the use of CSS in [XHTML 1.0]. Using a style attribute, an XHTML content author may assign a color to a particular paragraph. That author could also have used the style element at the top of the page to say that all paragraphs of a particular class or in a particular context would be colored red.

2.1.1 Local Approach

The document in Example 8 shows how a content author may use the ITS translate attribute to indicate that all content inside the author element should be protected from translation. Translation tools that are aware of the meaning of this attribute can then screen the relevant content from the translation process.

<dbk:article
  xmlns:its="http://www.w3.org/2005/11/its" 
  xmlns:dbk="http://docbook.org/ns/docbook" 
  its:version="1.0" version="5.0" xml:lang="en">
 <dbk:info>
  <dbk:title>An example article</dbk:title>
  <dbk:author
    its:translate="no">
   <dbk:personname>
    <dbk:firstname>John</dbk:firstname>
    <dbk:surname>Doe</dbk:surname>
   </dbk:personname>
   <dbk:affiliation>
    <dbk:address>
     <dbk:email>[email protected]</dbk:email>
    </dbk:address>
   </dbk:affiliation>
  </dbk:author>
 </dbk:info>
 <dbk:para>This is a short article.</dbk:para>
</dbk:article>

For this to work, the schema developer will need to add the translate attribute to the schema as a common attribute or on all the relevant element definitions. Note how there is an expectation in this case that inheritance plays a part in identifying which content does have to be translated and which does not. Tools that process this content for translation will need to implement the expected inheritance.

2.1.2 Global Approach

The document in Example 9 shows a different approach to identifying non-translatable content, similar to that used with a style element in [XHTML 1.0], but using an ITS-defined element called rules. It works as follows: A document can contain a rules element (placed where it does not impact the structure of the document, like in a "head" section). It contains one or more ITS rule elements (for example translateRule). Each of these specific elements contains a selector attribute. As its name suggests, this attribute selects the XML node or nodes to which a corresponding ITS information pertains. The values of ITS selector attributes are XPath absolute location paths. Information for the handling of namespaces in these path expressions is taken from namespace declarations [XML Names] at the current rules element.

<myTopic
  xmlns:its="http://www.w3.org/2005/11/its" 
  xmlns="myNamescapeURI" id="topic01" xml:lang="en-us">
 <prolog>
  <title>Using ITS</title>
  <its:rules version="1.0">
   <its:translateRule selector="//n:term" translate="no"/>
  </its:rules>
 </prolog>
 <body>
  <p>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.</p>
 </body>
</myTopic>

For this approach to work, the schema developer needs to add the rules element and associated markup to the schema.

In some cases this may allow the schema developer to avoid adding other ITS markup (such as an translate attribute) to the elements in the schema. However, it is likely that authors will want to use attributes on markup from time to time to override the general rule.

For specification of the Translate data category information, the contents of the rules element would normally be designed by an information architect familiar with the document format and familiar with, or working with someone familiar with, the needs of the localization group.

The global, rule-based approach has the following benefits:

• Content authors do not have to concern themselves with creating additional markup or verifying that the markup was applied correctly. ITS data categories are associated with sets of XML nodes (for example all p elements in an XML instance)

• Changes can be done in a single location, rather than by searching and modifying the markup throughout a document (or documents, if the rules element is stored as an external entity)

• ITS data categories can designate attribute values as well as elements.

• It is possible to associate ITS markup with existing markup (for example the term element in DITA)

The commonality in both examples above is the markup translate='no'. This piece of ITS markup can be interpreted as follows:

• it pertains to the Translate data category

• the attribute translate holds a value of "no"

The ITS selector attribute allows:

• ITS data category attributes to appear in global rules (even outside of an XML document or schema)

• ITS data categories attributes to pertain to sets of XML nodes (for example all p elements in an XML document)

• ITS markup to pertain to attributes

• ITS markup to associate with existing markup (for example the term element in DITA)

5.2.1 Global, Rule-based Selection

Global, rule-based selection is implemented using the rules element. It contains zero or more rule elements. Each rule element has a mandatory selector attribute. This attribute and all other possible attributes on rule elements are in the empty namespace and used without a prefix.

If there is more than one rules element in an XML document, the rules from each section are to be processed at the same precedence level. The rules sections are to be read in document order, and the ITS rules with them processed sequentially. The versions of these rules elements MUST NOT be different.

Depending on the data category and its usage, there are additional attributes for adding information to the selected nodes, or for pointing to existing information in the document. For example, the Localization Note data category can be used for adding notes to selected nodes, or for pointing to existing notes in the document. For the former purpose, a locNote element can be used. For the latter purpose, a locNotePointer attribute can be used.

Each data category allows you to add information to the selected nodes except for language information. Pointing to existing information is not possible for data categories that express a closed set of values, that is: Translate, Directionality and Elements Within Text.

The functionalities of adding information and pointing to existing information are mutually exclusive. That is: markup for pointing and adding MUST NOT appear in the same rule element.

Another difference between adding and pointing is the usage of XPath:

• The value of the selector attribute MUST be an XPath expression which starts with "/". That is, it must be an AbsoluteLocationPath as described in XPath 1.0 or its successor. This ensures that the selection is not relative to a specific location. The resulting nodes MUST be either element or attribute nodes.

• Attributes that point to existing information in the document, i.e. attributes whose name ends in ...Pointer, MUST use a RelativeLocationPath as described in XPath 1.0 or its successor. The XPath expression is evaluated relative to the nodes selected by the selector attribute. The following attributes point to existing information: locNotePointer, locNoteRefPointer, termInfoPointer, termInfoRefPointer, rubyPointer, rtPointer, rpPointer, rbcPointer, rtcPointer, rbspanPointer, langPointer.

If namespaces [XML Names] are used in XPath expressions in the selector attribute or the pointing attributes, the following rules MUST be applied while processing XPath:

1. For each prefix, there MUST be an xmlns attribute at the same rule element which allows to resolve the namespace URI of the prefix.

2. Element and attribute names without a prefix are interpreted as having no namespace.

3. To avoid a conflict with rule 2., default namespaces MUST NOT be used in the XPath expressions.

<its:rules
  xmlns:its="http://www.w3.org/2005/11/its" 
  xmlns:tei="http://www.tei-c.org/ns/1.0" version="1.0">
 <its:termRule selector="//tei:term" term="yes"/>
</its:rules>

<its:rules
  xmlns:its="http://www.w3.org/2005/11/its"  version="1.0">
 <its:termRule selector="//qterm" term="yes"/>
</its:rules>

Global rules can appear in the XML document they will be applied to, or in a separate XML document. The precedence of their processing depends on these variations. See also Section 5.4: Precedence between Selections.

Markup for global, rule-based selection is defined as follows.

rules

[1]	rules	::=	element its:rules { rules.content, rules.attributes }
[2]	rules.content	::=	( translateRule | locNoteRule | termRule | dirRule | rubyRule | langRule | withinTextRule )*
[3]	rules.attributes	::=	attribute version { xsd:float }, attribute xlink:href { xsd:anyURI }?, attribute xlink:type { "simple" }?

att.selector

[4]	att.selector.attributes	::=	att.selector.attribute.selector
[5]	att.selector.attribute.selector	::=	attribute selector { string }

att.version

[6]	att.version.attributes	::=	att.version.attribute.version
[7]	att.version.attribute.version	::=	attribute its:version { xsd:float }

5.2.2 Local Selection in an XML Document

Local selection in XML documents is realized with local ITS attributes, the ruby element, or the span element. span serves just as a carrier for the local ITS attributes and a container for ruby.

The content model of span permits arbitrary nesting of ruby markup, since the rb and rt elements themselves can contain span. An application of ruby MUST not use such arbitrary nesting.

The data category determines what is being selected. The necessary data category specific defaults are described in Section 6.1: Position, Defaults, Inheritance and Overriding of Data Categories.

<text
  xmlns:its="http://www.w3.org/2005/11/its" 
  its:version="1.0" xml:lang="en">
 <head
   its:translate="no">
  <author>Sven Corneliusson</author>
  <date>2006-09-26T17:34:04Z</date>
  <title
    its:translate="yes" role="header">Bidirectional Text</title>
 </head>
 <body>
  <par>In Arabic, the title <quote xml:lang="ar"
     its:dir="rtl">نشاط التدويل، W3C</quote>
     means <quote>Internationalization Activity, W3C</quote>.</par>
 </body>
</text>

Markup for local selection is defined as follows. The attribute group att.local.no-ns.attributes contains ITS attributes in no namespace and is used with the ITS elements span, locNote, ruby, rb, rt, rbc, rtc and rp. The attribute group att.local.with-ns.attributes contains namespace qualified ITS attributes and is used with elements from different namespaces.

att.local.no-ns

[8]	att.local.no-ns.attributes	::=	att.local.no-ns.attribute.translate, att.local.no-ns.attribute.locNote, att.local.no-ns.attribute.locNoteType, att.local.no-ns.attribute.locNoteRef, att.local.no-ns.attribute.termInfoRef, att.local.no-ns.attribute.term, att.local.no-ns.attribute.dir
[9]	att.local.no-ns.attribute.translate	::=	attribute translate { "yes" | "no" }?
[10]	att.local.no-ns.attribute.locNote	::=	attribute locNote { string }?
[11]	att.local.no-ns.attribute.locNoteType	::=	attribute locNoteType { "alert" | "description" }?
[12]	att.local.no-ns.attribute.locNoteRef	::=	attribute locNoteRef { xsd:anyURI }?
[13]	att.local.no-ns.attribute.termInfoRef	::=	attribute termInfoRef { xsd:anyURI }?
[14]	att.local.no-ns.attribute.term	::=	attribute term { "yes" | "no" }?
[15]	att.local.no-ns.attribute.dir	::=	attribute dir { "ltr" | "rtl" | "lro" | "rlo" }?

att.local.with-ns

[16]	att.local.with-ns.attributes	::=	att.local.with-ns.attribute.translate, att.local.with-ns.attribute.locNote, att.local.with-ns.attribute.locNoteType, att.local.with-ns.attribute.locNoteRef, att.local.with-ns.attribute.termInfoRef, att.local.with-ns.attribute.term, att.local.with-ns.attribute.dir
[17]	att.local.with-ns.attribute.translate	::=	attribute its:translate { "yes" | "no" }?
[18]	att.local.with-ns.attribute.locNote	::=	attribute its:locNote { string }?
[19]	att.local.with-ns.attribute.locNoteType	::=	attribute its:locNoteType { "alert" | "description" }?
[20]	att.local.with-ns.attribute.locNoteRef	::=	attribute its:locNoteRef { xsd:anyURI }?
[21]	att.local.with-ns.attribute.termInfoRef	::=	attribute its:termInfoRef { xsd:anyURI }?
[22]	att.local.with-ns.attribute.term	::=	attribute its:term { "yes" | "no" }?
[23]	att.local.with-ns.attribute.dir	::=	attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }?

span

[24]	span	::=	element its:span { span.content, span.attributes }
[25]	span.content	::=	( text | ruby | span )*
[26]	span.attributes	::=	att.local.no-ns.attributes

6.2.1 Definition

The Translate data category expresses information about whether the content of an element or attribute should be translated or not. The values of this data category are "yes" (translatable) or "no" (not translatable).

6.2.2 Implementation

The Translate data category can be expressed with global rules, or locally on an individual element. The information applies to the textual content of the element, including child elements, but excluding attributes. The default is that elements are translatable and attributes are not.

GLOBAL: The translateRule element contains the following:

• A required selector attribute. It contains an XPath expression which selects the nodes to which this rule applies.

• A required translate attribute with the value "yes" or "no".

<its:rules
  xmlns:its="http://www.w3.org/2005/11/its"  version="1.0">
 <its:translateRule translate="no" selector="//code"/>
</its:rules>

LOCAL: The following local markup is available for the Translate data category:

• A translate attribute with the value "yes" or "no".

<messages
  xmlns:its="http://www.w3.org/2005/11/its" 
  its:version="1.0">
 <msg num="123">Click Resume Button on Status Display or  
    <panelmsg
    its:translate="no">CONTINUE</panelmsg> Button
    on printer panel</msg>
</messages>

6.2.3 Markup Declarations for Translate

translateRule

[27]	translateRule	::=	element its:translateRule { translateRule.content, translateRule.attributes }
[28]	translateRule.content	::=	empty
[29]	translateRule.attributes	::=	att.selector.attributes, attribute translate { "yes" | "no" }

att.translate

[30]	att.translate.attributes	::=	att.translate.attribute.translate
[31]	att.translate.attribute.translate	::=	attribute its:translate { "yes" | "no" }?

6.3.1 Definition

The Localization Note data category is used to communicate notes to localizers about a particular item of content.

This data category can be used for several purposes, including, but not limited to:

• Tell the translator how to translate parts of the content

• Expand on the meaning or contextual usage of a specific element, such as what a variable refers to or how a string will be used on the user interface

• Clarify ambiguity and show relationships between items sufficiently to allow correct translation (e.g. in many languages it is impossible to translate the word "enabled" in isolation without knowing the gender, number and case of the thing it refers to.)

• Indicate why a piece of text is emphasized (important, sarcastic, etc.)

Two types of informative notes are needed:

• An alert contains information that the translator must read before translating a piece of text. Example: an instruction to the translator to leave parts of the text in the source language.

• A description provides useful background information that the translator will refer to only if they wish. Example: a clarification of ambiguity in the source text.

Editing tools may offer an easy way to create this type of information. Translation tools can be made to recognize the difference between these two types of localization notes, and present the information to translators in different ways.

6.3.2 Implementation

The Localization Note data category can be expressed with global rules, or locally on an individual element. The information applies to the textual content of the element, including child elements, but excluding attributes.

GLOBAL: The locNoteRule element contains the following:

• A required selector attribute. It contains an XPath expression which selects the nodes to which this rule applies.

• A required locNoteType attribute with the value "description" or "alert".

• Exactly one of the following:

  • A locNote element that contains the note itself and allows for local ITS markup.

  • A locNotePointer attribute that contains a relative XPath expression pointing to a node that holds the localization note.

  • A locNoteRef attribute that contains a URI referring to the location of the localization note.

  • A locNoteRefPointer attribute that contains a relative XPath expression pointing to a node that holds the URI referring to the location of the localization note.

<myRes
  xmlns:its="http://www.w3.org/2005/11/its" >
 <head>
  <its:rules version="1.0"
    its:translate="no">
   <its:locNoteRule locNoteType="alert" selector="//msg[@id='DisableInfo']">
    <its:locNote>The variable {0} has three possible values: 'printer', 
        'stacker' and 'stapler options'.</its:locNote>
   </its:locNoteRule>
  </its:rules>
 </head>
 <body>
  <msg id="DisableInfo">The {0} has been disabled.</msg>
 </body>
</myRes>

<Res
  xmlns:its="http://www.w3.org/2005/11/its" >
 <prolog>
  <its:rules version="1.0">
   <its:translateRule selector="//msg/notes" translate="no"/>
   <its:locNoteRule locNoteType="description" selector="//msg/data" locNotePointer="../notes"/>
  </its:rules>
 </prolog>
 <body>
  <msg id="FileNotFound">
   <notes>Indicates that the resource file {0} could not be loaded.</notes>
   <data>Cannot find the file {0}.</data>
  </msg>
  <msg id="DivByZero">
   <notes>A division by 0 was going to be computed.</notes>
   <data>Invalid parameter.</data>
  </msg>
 </body>
</Res>

<myRes
  xmlns:its="http://www.w3.org/2005/11/its" >
 <head>
  <its:rules version="1.0">
   <its:locNoteRule locNoteType="description" selector="//msg[@id='NotFound']" locNoteRef="ErrorsInfo.html#NotFound"/>
  </its:rules>
 </head>
 <body>
  <msg id="NotFound">Cannot find {0} on {1}.</msg>
 </body>
</myRes>

<dataFile
  xmlns:its="http://www.w3.org/2005/11/its" >
 <prolog>
  <its:rules version="1.0">
   <its:locNoteRule locNoteType="description" selector="//data" locNoteRefPointer="../@noteFile"/>
  </its:rules>
 </prolog>
 <body>
  <string id="FileNotFound" noteFile="Comments.html#FileNotFound">
   <data>Cannot find the file {0}.</data>
  </string>
  <string id="DivByZero" noteFile="Comments.html#DivByZero">
   <data>Invalid parameter.</data>
  </string>
 </body>
</dataFile>

LOCAL: The following local markup is available for the Localization Note data category:

• One of the following:

  • A locNote attribute that contains the note itself.

  • A locNoteRef attribute that contains a URI referring to the location of the localization note.

• An optional locNoteType attribute with the value "description" or "alert". If the locNoteType attribute is not present, the type of localization note will be assumed to be "description".

<msgList
  xmlns:its="http://www.w3.org/2005/11/its"  xml:space="preserve"
  its:version="1.0">
 <data name="LISTFILTERS_VARIANT"
   its:locNote="Keep the leading space!"
   its:locNoteType="alert">
  <value> Variant {0} = {1} ({2})</value>
 </data>
 <data
   its:locNote="%1\$s is the original text's date in the format YYYY-MM-DD HH:MM always in GMT">
  <value>Translated from English content dated <span id="version-info">%1\$s</span> GMT.</value>
 </data>
</msgList>

6.3.3 Markup Declarations for Localization Note

locNoteRule

[32]	locNoteRule	::=	element its:locNoteRule { locNoteRule.content, locNoteRule.attributes }
[33]	locNoteRule.content	::=	locNote?
[34]	locNoteRule.attributes	::=	att.selector.attributes, attribute locNotePointer { string }?, attribute locNoteType { "alert" | "description" }, attribute locNoteRef { xsd:anyURI }?, attribute locNoteRefPointer { string }?

locNote

[35]	locNote	::=	element its:locNote { locNote.content, locNote.attributes }
[36]	locNote.content	::=	( text | ruby | span )*
[37]	locNote.attributes	::=	att.local.no-ns.attributes

att.locNote

[38]	att.locNote.attributes	::=	att.locNote.attribute.locNote, att.locNote.attribute.locNoteType, att.locNote.attribute.locNoteRef
[39]	att.locNote.attribute.locNote	::=	attribute its:locNote { string }?
[40]	att.locNote.attribute.locNoteType	::=	attribute its:locNoteType { "alert" | "description" }?
[41]	att.locNote.attribute.locNoteRef	::=	attribute its:locNoteRef { xsd:anyURI }?

6.4.1 Definition

The Terminology data category is used to mark terms and optionally associate them with information, such as definitions. This helps to increase consistency across different parts of the documentation. It is also helpful for translation.

6.4.2 Implementation

The Terminology data category can be expressed with global rules, or locally on an individual element. There is no inheritance. The default is that neither elements nor attributes are terms.

GLOBAL: The termRule element contains the following:

• A required selector attribute. It contains an XPath expression which selects the nodes to which this rule applies.

• A required term attribute with the value "yes" or "no".

• Exactly one of the following:

  • A termInfoPointer attribute that contains a relative XPath expression pointing to a node that holds the terminology information.

  • A termInfoRef attribute that contains a URI referring to the resource providing information about the term.

  • A termInfoRefPointer attribute that contains a relative XPath expression pointing to a node that holds the URI referring to the location of the terminology information.

<text
  xmlns:its="http://www.w3.org/2005/11/its" >
 <its:rules version="1.0">
  <its:termRule selector="//term" term="yes" termInfoPointer="id(@def)"/>
 </its:rules>
 <p>We may define <term def="TDPV">discoursal point of view</term>
 as <gloss xml:id="TDPV">the relationship, expressed through discourse
  structure, between the implied author or some other addresser,
  and the fiction.</gloss>
 </p>
</text>

<text
  xmlns:its="http://www.w3.org/2005/11/its" >
 <its:rules version="1.0">
  <its:termRule selector="//term[1]" term="yes" termInfoRef="#TDPV"/>
 </its:rules>
 <p>We may define <term>discoursal point of view</term>
 as <gloss xml:id="TDPV">the relationship, expressed through discourse
  structure, between the implied author or some other addresser,
  and the fiction.</gloss>
 </p>
</text>

<text
  xmlns:its="http://www.w3.org/2005/11/its" >
 <its:rules version="1.0">
  <its:termRule selector="//term" term="yes" termInfoRefPointer="@target"/>
 </its:rules>
 <p>We may define <term target="#TDPV">discoursal point of view</term>
 as <gloss xml:id="TDPV">the relationship, expressed through discourse
  structure, between the implied author or some other addresser,
  and the fiction.</gloss>
 </p>
</text>

LOCAL: The following local markup is available for the Terminology data category:

• A term attribute with the value "yes" or "no".

• An optional termInfoRef attribute that contains a URI referring to the resource providing information about the term.

<book
  xmlns:its="http://www.w3.org/2005/11/its" 
  its:version="1.0">
 <head>...</head>
 <body> ...  <p>And he said: you need a
   new <quote
     its:term="yes">motherboard</quote>
  </p> ...
  </body>
</book>

6.4.3 Markup Declarations for Terminology

termRule

[42]	termRule	::=	element its:termRule { termRule.content, termRule.attributes }
[43]	termRule.content	::=	empty
[44]	termRule.attributes	::=	att.selector.attributes, attribute term { "yes" | "no" }, attribute termInfoRef { xsd:anyURI }?, attribute termInfoRefPointer { string }?, attribute termInfoPointer { string }?

att.term

[45]	att.term.attributes	::=	att.term.attribute.termInfoRef, att.term.attribute.term
[46]	att.term.attribute.termInfoRef	::=	attribute its:termInfoRef { xsd:anyURI }?
[47]	att.term.attribute.term	::=	attribute its:term { "yes" | "no" }?

6.5.1 Definition

The Directionality data category allows the user to specify the base writing direction of blocks, embeddings and overrides for the Unicode bidirectional algorithm. It has four values: "ltr", "rtl", "lro" and "rlo".

6.5.2 Implementation

The Directionality data category can be expressed with global rules, or locally on an individual element. The information applies to the textual content of the element, including child elements and attributes. The default is that both elements and attributes have the directionality of left-to-right.

GLOBAL: The dirRule element contains the following:

• A required selector attribute. It contains an XPath expression which selects the nodes to which this rule applies.

• A required dir attribute with the value "ltr", "rtl", "lro" or "rlo".

<text xml:lang="en">
 <body>
  <par>In Hebrew, the title <quote xml:lang="he" direction="rtlText">פעילות הבינאום, W3C</quote>
     means <quote>Internationalization Activity, W3C</quote>.</par>
 </body>
</text>

<its:rules
  xmlns:its="http://www.w3.org/2005/11/its"  version="1.0">
 <its:dirRule dir="rtl" selector="//*[@direction='rtlText']"/>
</its:rules>

LOCAL: The following local markup is available for the Directionality data category:

• A dir attribute with the value "ltr", "rtl", "lro" or "rlo".

<text
  xmlns:its="http://www.w3.org/2005/11/its"  xml:lang="en"
  its:version="1.0">
 <body>
  <par>In Arabic, the title <quote xml:lang="ar"
     its:dir="rtl">نشاط التدويل، W3C</quote>
     means <quote>Internationalization Activity, W3C</quote>.</par>
 </body>
</text>

6.5.3 Markup Declarations for Directionality

dirRule

[48]	dirRule	::=	element its:dirRule { dirRule.content, dirRule.attributes }
[49]	dirRule.content	::=	empty
[50]	dirRule.attributes	::=	att.selector.attributes, attribute dir { "ltr" | "rtl" | "lro" | "rlo" }

att.dir

[51]	att.dir.attributes	::=	att.dir.attribute.dir
[52]	att.dir.attribute.dir	::=	attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }?

6.6.1 Definition

The Ruby data category is used for a run of text that is associated with another run of text, referred to as the base text. Ruby text is used to provide a short annotation of the associated base text. It is most often used to provide a reading (pronunciation) guide.

6.6.2 Implementation

The Ruby data category can be expressed with global rules, or locally. There is no inheritance.

GLOBAL: The rubyRule element contains the following:

• A required selector attribute. It contains an XPath expression which selects the nodes to which this rule applies. This is the ruby base text.

• An optional rubyPointer attribute that contains a relative XPath expression pointing to a node that corresponds to the ruby element.

• An optional rpPointer attribute that contains a relative XPath expression pointing to a node that corresponds to the ruby parenthesis.

• An optional rbcPointer attribute that contains a relative XPath expression pointing to a node that corresponds to the ruby base container.

• An optional rtcPointer attribute that contains a relative XPath expression pointing to a node that corresponds to the ruby text container.

• An optional rbspanPointer attribute that contains a relative XPath expression pointing to a node that corresponds to the rbspan attribute.

• An optional rubyText element that contains the ruby text.

• An optional rtPointer attribute that contains a relative XPath expression pointing to a node that corresponds to the ruby text.

<text
  xmlns:its="http://www.w3.org/2005/11/its" >
 <head> ... 
   <its:rules version="1.0">
   <its:rubyRule selector="/text/body/img[1]/@alt">
    <its:rubyText>World Wide Web Consortium</its:rubyText>
   </its:rubyRule>
  </its:rules>
 </head>
 <body>
  <img src="w3c_home.png" alt="W3C"/> ...
  </body>
</text>

LOCAL: In a document, the Ruby data category is realized with a ruby element. It contains the following:

• An rb element that contains the ruby base text and allows for local ITS markup.

• An rp element that contains the ruby parenthesis. It is used in case of simple markup to specify characters that can denote the beginning and end of ruby text when user agents do not have other ways to present ruby text distinctively from the base text.

• An rt element that contains the ruby text and allows for local ITS markup. It has an optional rbspan attribute. The rbspan attribute allows an rt element to span multiple rb elements.

• An rbc element that contains the ruby base container.

• An rtc element that contains the ruby text container.

All these elements share the attributes of the span element.

<text
  xmlns:its="http://www.w3.org/2005/11/its" 
  its:version="1.0">
 <head> ... </head>
 <body>
  <p>この本は <its:ruby>
    <its:rb>慶応義塾大学</its:rb>
    <its:rp>(</its:rp>
    <its:rt>けいおうぎじゅくだいがく</its:rt>
    <its:rp>)</its:rp>
   </its:ruby>の歴史を説明するものです。</p>
 </body>
</text>

6.6.3 Markup Declarations for Ruby

rubyRule

[53]	rubyRule	::=	element its:rubyRule { rubyRule.content, rubyRule.attributes }
[54]	rubyRule.content	::=	rubyText?
[55]	rubyRule.attributes	::=	att.selector.attributes, attribute rubyPointer { string }?, attribute rtPointer { string }?, attribute rpPointer { string }?, attribute rbcPointer { string }?, attribute rtcPointer { string }?, attribute rbspanPointer { string }?

rubyText

[56]	rubyText	::=	element its:rubyText { rubyText.content, rubyText.attributes }
[57]	rubyText.content	::=	text
[58]	rubyText.attributes	::=	att.local.no-ns.attributes, attribute rbspan { string }?

ruby

[59]	ruby	::=	element its:ruby { ruby.content, ruby.attributes }
[60]	ruby.content	::=	( rb, ( rt | ( rp, rt, rp ) ) ) | ( rbc, rtc, rtc? )
[61]	ruby.attributes	::=	att.local.no-ns.attributes

rb

[62]	rb	::=	element its:rb { rb.content, rb.attributes }
[63]	rb.content	::=	( text | span )*
[64]	rb.attributes	::=	att.local.no-ns.attributes

rt

[65]	rt	::=	element its:rt { rt.content, rt.attributes }
[66]	rt.content	::=	( text | span )*
[67]	rt.attributes	::=	att.local.no-ns.attributes, attribute rbspan { string }?

rbc

[68]	rbc	::=	element its:rbc { rbc.content, rbc.attributes }
[69]	rbc.content	::=	rb+
[70]	rbc.attributes	::=	att.local.no-ns.attributes

rtc

[71]	rtc	::=	element its:rtc { rtc.content, rtc.attributes }
[72]	rtc.content	::=	rt+
[73]	rtc.attributes	::=	att.local.no-ns.attributes

rp

[74]	rp	::=	element its:rp { rp.content, rp.attributes }
[75]	rp.content	::=	text
[76]	rp.attributes	::=	att.local.no-ns.attributes

6.7.1 Definition

The element langRule is used to express the language of a given piece of content. The langPointer attribute points to the markup which expresses the language of the text selected by the selector attribute. This markup MUST use values that conform to [BCP47]. The recommended way to specify language identification is to use xml:lang. The langRule element is intended only as a fall-back mechanism for documents where language is identified with another construct.

<its:rules
  xmlns:its="http://www.w3.org/2005/11/its"  version="1.0">
 <its:langRule selector="//p" langPointer="@mylangattribute"/>
</its:rules>

6.7.2 Implementation

The Language Information data category can be expressed only with global rules. The information applies to the textual content of the element, including child elements and attributes. There is no default.

GLOBAL: The langRule element contains the following:

• A required selector attribute. It contains an XPath expression which selects the nodes to which this rule applies.

• A required langPointer attribute that contains a relative XPath expression pointing to a node that contains language information.

6.7.3 Markup Declarations for Language Information

langRule

[77]	langRule	::=	element its:langRule { langRule.content, langRule.attributes }
[78]	langRule.content	::=	empty
[79]	langRule.attributes	::=	att.selector.attributes, attribute langPointer { string }

6.8.1 Definition

The Elements Within Text data category reveals if and how an element affects the way text content behaves from a linguistic viewpoint. This information is for example relevant to provide basic text segmentation hints for tools such as translation memory systems. The values associated with this data category are:

• "yes" : The element and its content are part of the flow of its parent element. For example the element strong in [XHTML 1.0]:

  <strong>Appaloosa horses</strong> have spotted coats.

• "nested" : The element is part of the flow of its parent element, its content is an independent flow. For example the element fn in [DITA 1.0]:

  Palouse horses<fn>A Palouse horse is the same as an Appaloosa.</fn> have spotted coats.

• "no" : The element splits the text flow of its parent element and its content is an independent text flow. For example the element p when inside the element li in DITA or XHTML:

  <li>Palouse horses: <p>They have spotted coats.</p> <p>They have been bred by the Nez Perce.</p> </li>

6.8.2 Implementation

The Elements Within Text data category can be expressed only with global rules. There is no inheritance. The default is that elements are not within text.

GLOBAL: The withinTextRule element contains the following:

• A required selector attribute. It contains an XPath expression which selects the nodes to which this rule applies.

• A required withinText attribute with the value "yes", "no" or "nested".

<its:rules
  xmlns:its="http://www.w3.org/2005/11/its"  version="1.0">
 <its:withinTextRule withinText="yes" selector="//b | //em | //i"/>
</its:rules>

6.8.3 Markup Declarations for Elements Within Text

withinTextRule

[80]	withinTextRule	::=	element its:withinTextRule { withinTextRule.content, withinTextRule.attributes }
[81]	withinTextRule.content	::=	empty
[82]	withinTextRule.attributes	::=	att.selector.attributes, attribute withinText { "yes" | "no" | "nested" }