[ contents ]

W3C

Internationalization Tag Set (ITS) Version 1.0

W3C Working Draft 18 May 2006

This version:
http://www.w3.org/TR/2006/WD-its-20060518/
Latest version:
http://www.w3.org/TR/its/
Previous version:
http://www.w3.org/TR/2006/WD-its-20060414/
Editors:
Christian Lieske, SAP AG
Felix Sasaki, W3C

This document is also available in these non-normative formats: ODD/XML document and XHTML Diff markup to publication from 14 April 2006.


Abstract

This document defines data categories and their implementation as a set of elements and attributes called the Internationalization Tag Set (ITS). ITS is designed to be used with schemas to support the internationalization and localization of schemas and documents. An implementation is provided for three schema languages: XML DTD, XML Schema and RELAX NG.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a Last Call Working Draft of "Internationalization Tag Set (ITS) Version 1.0".

This document defines data categories and their implementation as a set of elements and attributes called the Internationalization Tag Set (ITS). ITS is designed to be used with schemas to support the internationalization and localization of schemas and documents. An implementation is provided for three schema languages: XML DTD, XML Schema and RELAX NG. See the latest revision log for changes since the last publication of this document.

This document was developed by the Internationalization Tag Set (ITS) Working Group, part of the W3C Internationalization Activity. The Working Group expects to advance this Working Draft to Recommendation Status. A complete list of changes to this document is available.

The W3C Membership and other interested parties are invited to review the document and send comments through 30 June 2006. The Working Group is managing comments on this document using W3C's public Bugzilla system. We recommend using Bugzilla for making comments (instructions can be found at How to use the Issues Tracking System for the ITS Tagset Working Draft). If this is not feasible, comments may also be sent to www-i18n-comments@w3.org. Use "[Comment on ITS WD]" in the subject line of your email. ITS tagset related comments and issues in Bugzilla and the www- i18n-comments archives are publicly available.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

Appendices

A Schemas for ITS (Non-Normative)
B Checking ITS Markup Constraints (Non-Normative)
C References
D References (Non-Normative)
E Revision Log (Non-Normative)
F Acknowledgements (Non-Normative)

Go to the table of contents.1 Introduction

This section is informative.

This document defines a standard for high-quality, cost efficient internationalization and localization of schemas and XML instances (both existing ones and new ones). On the one hand, the standard is defined conceptually through the notion of data categories. On the other hand, the standard defines implementations of these data categories as a set of elements and attributes called the Internationalization Tag Set (ITS). The document provides examples of how ITS can be used with existing popular markup schemes such as DocBook. Furthermore, the document provides implementations for three schema languages: XML DTD [ XML 1.0], XML Schema [XML Schema] and RELAX NG [RELAX NG].

Requirements for this document are formulated in [ITS REQ]. Not all requirements listed there are addressed in this document. Those which are not addressed here are either covered in [XML i18n BP] or may be addressed in a future version of this specification.

This document covers the following requirements:

The following requirements will be addressed in [XML i18n BP]:

The Working Group decided not to cover the following requirements at this time to be able to focus on the most important ones.

Go to the table of contents.1.1 Users and Usages of ITS

Go to the table of contents.1.1.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 (aka “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 the required markup is available, and that the behaviour 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, and the ITS specification provides examples of how those formats (aka “host vocabulary”) could be used with ITS.

    Note:

    The Working Group covers the question “How use ITS with existing popular markup schemes?” in more detail 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.6: Associating ITS Data Categories with Existing Markup). The developer should, however, check that the behaviour 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 users encompasses companies which provide tools for authoring, translation or other flavours 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 standardising 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 users comprises authors, translators and other types of content authors. The markup proposed in this specification may be used by them to mark up specific bits of content. Aside: The burden of inserting markup should 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 internationalization and localization of content is provided in this specification in two ways:

Go to the table of contents.1.1.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 answer the question, 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

Example 1: Use of ITS by content author
<book its:version="1.0">
 <head>...</head>
 <body> ...  <p>And he said: you need a
   new <quote its:translate="no">T-Model</quote>
  </p> ...
  </body>
</book>

[EX-ways-to-use-its-1.xml]

  • 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.

Example 2: Use of ITS by information architect
<text>
 <head>
  <its:rules its:version="1.0">
   <its:translateRule translate="no" selector="//dt"/>
  </its:rules>
 </head>
 <body> ...
   <p> ... <dl>
    <dt>...</dt>
    <dd>...</dd>
   </dl>
  </p>
 </body>
</text>

[EX-ways-to-use-its-2.xml]

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

Example 3: Use of ITS by processor
<text>
 <head>
  <its:rules its:version="1.0" xlink:href="myRules.xml"/>
 </head>
 <body> ...
   <p> ... <dl>
    <dt>...</dt>
    <dd>...</dd>
   </dl>
  </p>
 </body>
</text>

[EX-ways-to-use-its-3.xml]

  • 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.

The first two approaches above can be likened to the use of CSS in XHTML. Using a style attribute, an XHTML content author may assign a colour 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 coloured red.

Go to the table of contents.1.2 Motivation for ITS

Content or software that is authored in one language (so-called source language) is often made available in additional languages or adapted with regard to other cultural aspects. This is done through a process called localization, where the original material is translated and adapted to the target audience.

In addition, document formats expressed by schemas may be used by people in different parts of the world, and these people may need special markup to support the local language or script. For example, people authoring in languages such as Arabic, Hebrew, Persian or Urdu need special markup to demarcate directionality in mixed direction text.

From the viewpoints of feasibility, cost, and efficiency, it is important that the original material should be suitable for localization. This is achieved by appropriate design and development, and the corresponding process is referred to as internationalization. For a detailed explanation of the terms "localization" and "internationalization", see [l10n i18n].

The increasing usage of XML as a medium for documentation-related content (e.g. DocBook, and DITA as formats for writing structured documentation, well suited to computer hardware and software manuals) and software-related content (e.g. the eXtensible User Interface Language [XUL]) creates challenges and opportunities in the domain of XML internationalization and localization.

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.

Example 4: Document with partially translatable content

PhaseCode should not be translated; the title attribute sometimes has to be translated and sometimes must not be translated.

<Manual>
 <Info>
  <PhaseCode>Review Level</PhaseCode>
  <FormNo>8U81-GS-52C</FormNo>
  <Name>Owner's Manual</Name>
   ...
  </Info>
 <Section id="0" title="#Introduction#">
  <Ltitle id="005" title="#ZOOM#">
   <Mtitle
     id="00501"
     title="Getting started"
     option="no"
     cols="1">
    <MultiCol cols="1">
     <Text>Some text to localize</Text>
    
        ...
        </MultiCol>
   </Mtitle>
  </Ltitle>
 </Section>
</Manual>

[EX-motivation-its-1.xml]

Example 5: Document with partially translatable content

The first file name in the first component element would not be translated.

<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>
 </rsrc>
</dialogue>

[EX-motivation-its-2.xml]

Example 6: Document with partially translatable content

In the example below, there are no clear mechanisms allowing one to know which string element needs to be translated.

<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>

[EX-motivation-its-3.xml]

Go to the table of contents.1.3 Out of Scope

This standard does not exhaustively cover all mechanisms and data formats which might be needed for configuring localization workflows or tools to process a specific format. These mechanisms and data formats, sometimes called Localization Properties, however, possibly may be implemented by the framework put forth in this standard.

Note:

“XML localization properties” is a generic term to name the mechanisms and data formats that allows localization tools to be configured in order to process a specific XML format. Examples of "XML localization properties" are: the "Trados DTD Settings" file, and the SDLX "Analysis" file.

Go to the table of contents.1.4 Important Design Principles

Abstraction via data categories: ITS defines data categories as an abstract notion for information for internationalization and localization of XML schemas and documents. This abstraction is helpful in realizing independence from a particular implementation e.g. using an element or attribute. See Section 3.3: Data category for a definition of the term data categories, Section 6: Description of Data Categories for the definition of the various ITS data categories, and subsections in Section 6: Description of Data Categories for the data category implementations.

Powerful selection mechanism: For ITS markup which appears in an XML instance, it has to be clearly defined to which XML nodes the ITS-related information pertains. Thus, ITS defines selection mechanisms to specify to what parts of an XML document an ITS data category and its values should be applied. Selection relies on the information which is given in the XML Information Set [XML Infoset]. ITS applications may implement inclusion mechanisms such as XInclude or DITA's [DITA 1.0] conref.

Content authors need for example a simple way to work with the translatability data category in order to express whether the content of an element or attribute should be translated or not. Localization coordinators, on the other hand, need an efficient way for managing translations of large document sets based on the same schema. This could by realized by a specification of defaults for translatability and exceptions from the defaults (e.g. all p elements should be translated, but not p elements inside of an index element).

This specification responds to these requirements by introducing mechanisms for specifying ITS information in XML documents, see Section 5: Processing of ITS information. These mechanisms also provide a means for specifying ITS information for attributes (a task for which no standard means yet exists). The ITS mechanisms for selection are:

  • as for XML documents, usable local (at the XML node to which it pertains) or globally (not at the XML node to which it pertains)
  • as for global usage: possibly in the target XML document or in a separate file

No dedicated extensibility: It may be useful or necessary to extend the set of information available for internationalization or localization purposes beyond what is provided by ITS. This specification does not define a dedicated extension mechanism, since ordinary XML mechanisms (e.g. XML Namespaces [XML Names]) may be used.

Ease of integration:

  • ITS follows the example from section 4 of [XLink 1.0], by providing mostly global attributes for the implementation of ITS data categories. Avoiding elements for ITS purposes as much as possible ensures ease of integration into existing markup schemes, see section 3.14 in [ITS REQ]. Only for some requirements additional child elements have to be used, see for example Section 6.6: Ruby.
  • ITS has no dependency on technologies which are still under development
  • ITS fits with existing work in the W3C architecture (e.g. use of XPath [XPath 1.0] for the selection mechanism)

Go to the table of contents.1.5 Development of this Specification

This specification has been developed using the ODD (One Document Does it all) language of the Text Encoding Initiative ([TEI]). This is a literate programming language for writing XML schemas, with three characteristics:

  1. The element and attribute set is specified using an XML vocabulary which includes support for macros (like DTD entities, or schema patterns), a hierarchical class system for attributes and elements, and creation of modules.
  2. The content models for elements and attributes are written using embedded RELAX NG XML notation.
  3. Documentation for elements, attributes, value lists etc. is written inline, along with examples and other supporting material.

XSLT transformations are provided by the TEI to extract documentation in HTML, XSL FO or LaTeX forms, and to generate RELAX NG documents and DTD. From the RELAX NG documents, James Clark's trang can be used to create XML Schema documents.

Go to the table of contents.2 Basic Concepts

This section is informative.

Information (e.g. "translate this") captured by ITS markup (e.g. its:translate='yes') always pertains to one or more XML nodes (mainly element and attribute nodes). In a sense, ITS markup “selects” the XML node(s). Selection may be explicit or implicit. ITS distinguishes two approaches to selection: local, and with global rules.

The mechanisms defined for ITS selection resemble those defined in [CSS2]. The local approach can be compared to the style attribute in CSS, and the approach with global rules is similar to the style element in CSS. In contrast to CSS, ITS uses XPath for identifying nodes. Thus, the

ITS markup can be used with XML documents (e.g. a DocBook article), or schemas (e.g. an XML Schema document for a proprietary document format). Since each usage defines some specific requirements, ITS markup may take different shapes.

The following two examples sketch the distinction between the local and global approaches.

Example 7: ITS markup on elements in an XML document (local approach)
<article its:version="1.0" its:translate="yes">
 <info>
  <title>An example article</title>
  <author its:translate="no">
   <personname>
    <firstname>John</firstname>
    <surname>Doe</surname>
   </personname>
   <affiliation>
    <address>
     <email>foo@example.com</email>
    </address>
   </affiliation>
  </author>
 </info>
</article>

[EX-basic-concepts-1.xml]

The example above shows how a content author may use the ITS translate attribute to indicate what text should be translated and what text 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.

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.

Example 8: ITS global markup in an XML document (rule-based approach)
<topic id="myTopic" xml:lang="en-us">
 <title>Using ITS</title>
 <prolog>
  <its:rules its:version="1.0">
   <its:translateRule selector="//term" translate="no"/>
  </its:rules>
 </prolog>
 <body>
  <p>An <term>ITS namespace</term> definition exists...</p>
 </body>
</topic>

[EX-basic-concepts-2.xml]

The example above shows a different approach to identifying non-translatable content, similar to that used with a style element in XHTML, but using an ITS-defined element called rules. It works as follows: A document can contain a rules element (it is recommended to use a “head” section), which contains one or more data category specific ITS elements (for example translateRule). Each of these specific elements contains a selector attribute. As its name suggests, this attribute selects (or designates) 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 contained in the ITS element ns which is a child of rules.

For this 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 translatability 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:

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

To summarize: The examples with global and local usage of ITS markup show that ITS markup, in some cases, appears in elements defined by ITS itself (the translateRule element (embedded within a rules element)) and in other cases appears in elements of the host vocabulary. In addition to one or more ITS data category specific attributes, translateRule or other rule elements contain a corresponding selector attribute. As their name suggests, a selector selects (or designates) one or more XML nodes (namely those to which a corresponding ITS data category attribute pertains). The value of ITS selector attributes are XPath absolute location paths. Information for to the handling of namespaces in these path expression is contained in the ITS element ns which is a child of rules.

The ITS selector attribute allows:

The power of the ITS selection mechanisms comes at a price: rules related to overriding/precedence, and inheritance, have to be established.

Example 9: Overriding and Inheritance
<text>
 <head>
  <its:rules its:version="1.0">
   <its:translateRule translate="yes" selector="//p"/>
  </its:rules>
 </head>
 <body>
  <p its:translate="no"> ... <dl>
    <dt>...</dt>
    <dd>...</dd>
   </dl>
  </p>
 </body>
</text>

[EX-basic-concepts-3.xml]

In this example, the ITS data category attribute translate appears twice: in a rules element, and on a specific p element. Since the ITS selector attribute in the rules element selects all p elements, a question arises: What is the value for the translatability data category of the p element which has local markup? ITS provides precedence and inheritance rules which answer questions like this. In the example, the value is "no" (that is to say, the content of the p element should not be translated).

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 data category for localization information can be used to add information to selected nodes, or to point at existing information in the document. For the former purpose, a locInfo element can be used. For the latter purpose, a locInfoPointer attribute can be used.

The functionality of adding information to the selected nodes is available for each data category except language information. Pointing to existing information is not possible for data categories which express a closed set of values, that is: translatability, directionality and elements within text.

The functionalities of adding information and pointing to existing information are mutually exclusive. That is to say, attributes for pointing and adding must not appear at the same rule element.

Go to the table of contents.3 Notation and Terminology

This section is normative.

Go to the table of contents.3.1 Notation

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].

The namespace URI that MUST be used by implementations of this specification is:

http://www.w3.org/2005/11/its

The namespace prefix used in this specification for this URI is "its". It is recommended that implementations of this specification use this prefix.

In addition, the following namespaces are used in this document:

  • http://www.w3.org/2001/XMLSchema for the XML Schema namespace, here used with the prefix "xs"
  • http://relaxng.org/ns/structure/1.0 for the RELAX NG namespace, here used with the prefix "rng"
  • http://www.w3.org/1999/xlink for the XLink namespace, here used with the prefix "xlink"

Go to the table of contents.3.2 Schema Language

[Definition: Schema language refers in this specification to an XML-related modelling or validation language such as XML DTD, XML Schema or RELAX NG.]

Note:

This specification provides schemas in the format of XML DTD, XML Schema or RELAX NG. However, these schemas are only non-normative: conformance for ITS markup declarations defines only mandatory positions of ITS declarations in schemas. This makes it possible to use ITS with any schema language which allows for using these positions.

Go to the table of contents.3.3 Data category

[Definition: ITS defines data category as an abstract concept for a particular type of information for internationalization and localization of XML schemas and documents.] The concept of a data category is independent of its implementation in an XML environment (e.g. using an element or attribute).

For each data category, ITS distinguishes between the following:

Example 10: A data category and its implementation

The data category translatability conveys information as to whether a piece of content should be translated or not.

The simplest formalization of this prose description on a schema language independent level is a translate attribute with two possible values: "yes" and "no". An implementation on a schema language specific level would be the declaration of the translate attribute in e.g. an XML DTD, an XML Schema document or an RELAX NG document. A different implementation would be a translateRule element which allows for specifying global rules about translatability.

Go to the table of contents.3.4 Selection

[Definition: selection encompasses mechanisms to specify to what parts of an XML document an ITS data category and its values should be applied to.] Selection is discussed in detail in Section 5: Processing of ITS information. Selection can be applied globally, see Section 5.3.1: Global, Rule-based Selection, and locally, see Section 5.3.2: Local Selection in an XML Document. As for global selection, ITS information can be added to the selected nodes, or it can point to existing information which is related to selected nodes.

Selection relies on the information which is given in the XML Information Set [XML Infoset]. ITS applications MAY implement inclusion mechanisms such as XInclude or DITA's [DITA 1.0] conref.

Note:

The selection of the ITS data categories applies to text nodes. In some cases these nodes form pointers to other resources; a well-known example is the src attribute on the img element in HTML. The ITS translatability data category applies to the text of the pointer itself, not the object to which it points. Thus in the following example, the translation information specified via the translateRule element applies to the filename "instructions.jpg", and is not an instruction to open the graphic and change the words therein.

Example 11: Selecting the text of a pointer to an external object
<text>
 <its:rules its:version="1.0">
  <its:translateRule translate="yes" selector="//p/img/@src"/>
 </its:rules> ...
 <p>As you can see in
  <img src="instructions.jpg"/>,
  the truth is not always out there.</p>
</text>

[EX-notation-terminology-1.xml]

Go to the table of contents.4 Conformance

This section is normative.

The usage of the term conformance clause in this section is in compliance with [QAFRAMEWORK].

This specification defines two types of conformance: conformance of 1) ITS markup declarations , and conformance of 2) processing expectations for ITS Markup. These conformance types complement each other. An implementation of this specification MAY use them separately or together.

Go to the table of contents.4.1 Conformance Type 1: ITS Markup Declarations

Description: ITS markup declarations encompass all declarations which are part of the Internationalization Tag Set. They do not concern the usage of the markup in XML documents. Such markup is subject to the conformance clauses in Section 4.2: Conformance Type 2: The Processing Expectations for ITS Markup.

Definitions related to this conformance type: ITS markup declarations are defined in various subsections in Section 5: Processing of ITS information and Section 6: Description of Data Categories (e.g. Section 6.3.3: Markup Declarations for Localization Information) in a schema language independent manner, relying on the ODD language. Their occurrence in other sections of this document is typographically marked via bold face and color.

Who uses this conformance type: Schema designers integrating ITS markup declarations into a schema. All conformance clauses for this conformance type concern the position of ITS markup declarations in that schema, and their status as mandatory or optional.

Conformance clauses:

  • 1-1: At least one of the following MUST be in the schema:

  • 1-2: If the rules element is used, it MUST be part of the content model of at least one element declared in the schema. It SHOULD be in a content model for meta information, if this is available in that schema (e.g. the head element in XHTML).

  • 1-3: If the ruby element is used, it SHOULD be declared as an inline element.

  • 1-4: If the span element is used, it SHOULD be declared as an inline element.

Full implementations of this conformance type will implement all markup declarations for ITS. Statements related to this conformance type MUST list all markup declarations they implement.

Examples: Examples of the usage of ITS markup declarations in various existing schemas are given in a separate document [XML i18n BP].

Note:

Since the ITS markup declarations are schema language independent, each schema language can use its own, possibly multiple mechanisms to implement the conformance clauses for ITS markup declarations. For example, an XML DTD can use parameter entities to encapsulate the ITS local attributes, or declare them directly for each element. The appropriate steps to integrate ITS into a schema depend on the design of this schema (e.g. whether it already has a customization layer which uses parameter entities). The ITS schemas in the format of XML DTD, XML Schema and RELAX NG in Appendix A: Schemas for ITS are only informative examples.

Go to the table of contents.4.2 Conformance Type 2: The Processing Expectations for ITS Markup

Description: Processors need to compute the ITS information which pertains to a node in an XML document. The ITS processing expectations define how the computation has to be carried out. Correct computation involves support for selection mechanism, defaults, and precedence. The markup MAY be valid against a schema which conforms to the clauses in Section 4.1: Conformance Type 1: ITS Markup Declarations.

Definitions related to this conformance type: The processing expectations for ITS markup make use of selection mechanisms defined in Section 5: Processing of ITS information. The individual data categories defined in Section 6: Description of Data Categories have default selections, and allow for using ITS markup in various positions (global and local). In addition, a set of processing expectations specific to the ruby data category and the directionality data category, refer to external specifications.

Who uses this conformance type: Applications which need to process for internationalization or localization the nodes captured by a data category. Examples for this type of application are: ITS markup-aware editors, or translation tools which make use of ITS markup to filter translatable text as an input to the localization process.

Note:

Application-specific processing (that is processing which goes beyond the computation of ITS information for a node) such as automated filtering of translatable content based on the translatability data category is not covered by the conformance clauses below.

Conformance clauses:

Statements related to this conformance type MUST list all data categories they implement, and for each data category which type of selection they support.

Go to the table of contents.5 Processing of ITS information

This section is normative.

Go to the table of contents.5.1 Summary of ITS Markup

The following list summarizes elements relating to global rules and their attributes:

  • <rules> Container for global rules.

    href

    Pointer to external rules files.

    Attributes inherited from [att.version]

  • <ns> An element to describe namespace URIs and prefixes within XPath expressions in rules elements.

    prefix

    The namespace prefix used in selection expressions.

    uri

    The namespace being identified.

  • <dirRule> Rule about directionality.

    dir

    The text direction for the selection.

    Legal values are:

    ltr

    rtl

    lro

    rlo

    Attributes inherited from [att.selector]

  • <langRule> Rule about language identification markup.

    langPointer

    Relative XPath expression pointing to a node which contains language information.

    Attributes inherited from [att.selector]

  • <locInfo> Contains localization information. Attributes inherited from [att.translate att.locInfo att.term att.dir]

  • <locInfoRule> Rule about localization information.

    locInfoPointer

    Relative XPath expression pointing to a node that holds the localization information.

    locInfoType

    The type of localization information.

    Legal values are:

    alert

    description

    locInfoRef

    URI referring to the location of the localization information.

    locInfoRefPointer

    Relative XPath expression pointing to a node that holds the URI referring to the location of the localization information.

    Attributes inherited from [att.selector]

  • <termRule> Rule about terminological information.

    termInfoRef

    Pointer to a resource containing information about the term.

    termInfoRefPointer

    The location of a local pointer to a resource containing information about the term.

    Attributes inherited from [att.selector]

  • <translateRule> Rule about translatability.

    translate

    The translatability information to be applied to selected nodes.

    Legal values are:

    yes

    no

    Attributes inherited from [att.selector]

  • <withinTextRule> Rule about markup of "intext" elements.

    withinText

    States whether current context is regarded as "within text".

    Legal values are:

    yes

    no

    nested

    Attributes inherited from [att.selector]

  • <rubyRule> Rule about Ruby markup.

    rubyPointer

    Relative XPath expression pointing to a node which corresponds to a ruby element

    rbPointer

    Relative XPath expression pointing to a node which corresponds to a rb element

    rtPointer

    Relative XPath expression pointing to a node which corresponds to a rt element

    rpPointer

    Relative XPath expression pointing to a node which corresponds to a rp element

    rbcPointer

    Relative XPath expression pointing to a node which corresponds to a rbc element

    rtcPointer

    Relative XPath expression pointing to a node which corresponds to a rtc element

    rubyText

    Ruby text.

    rbspanPointer

    Relative XPath expression pointing to a node which corresponds to a rbspan attribute.

    Attributes inherited from [att.selector]

The following list summarizes elements and attributes to be used locally:

Go to the table of contents.5.2 Indicating the Version of ITS

The version of the ITS schema defined in this specification is "1.0". The version is indicated by the ITS version attribute. This attribute is mandatory for the rules element, where it MUST be in the ITS namespace and use its prefix, e.g. its:version. If there is no rules element in an XML document, the ITS version attribute MUST be provided on the root element of the document. If there is both a version attribute at the root element and a rules element in a document, they MUST NOT specify different versions.

Each XML document can have a different version. That is: if external rules are linked via an XLink href attribute on the rules element, they can specify a different version than the rules element.

Go to the table of contents.5.3 Locations of Data Categories

ITS data categories can appear in two places:

The two locations are described in detail below.

Go to the table of contents.5.3.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 at 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 data category localization information can be used for adding information to selected nodes, or for pointing to existing information in the document. For the former purpose, an locInfo element can be used. For the latter purpose, a locInfoPointer attribute can be used.

The functionality of adding information to the selected nodes is available for each data category except language information. Pointing to existing information is not possible for data categories which express a closed set of values, that is: translatability, 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 at 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]. This ensures that the selection is not relative to a specific location. The resulting nodes MUST be either element or attribute nodes.

  • As for data category specific attributes like locInfoPointer which point to existing information in the document, a RelativeLocationPath as described in [XPath 1.0] MUST be used. The XPath expression is evaluated relative to the nodes which are selected via the selector attribute.

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 ns element as a child of the rules element. The ns element has two attributes prefix (for the namespace prefix) and uri (for the namespace URI).
  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.
Example 12: XPath expressions with namespaces

The term element from the TEI is in a namespace http://www.tei-c.org/ns/1.0.

<its:rules its:version="1.0">
 <its:ns prefix="tei" uri="http://www.tei-c.org/ns/1.0"/>
 <its:termRule selector="//tei:term"/>
</its:rules>

[EX-selection-global-1.xml]

Example 13: XPath expressions without namespaces

The qterm element from DocBook is in no namespace.

<its:rules its:version="1.0">
 <its:termRule selector="//qterm"/>
</its:rules>

[EX-selection-global-2.xml]

Note:

The usage of the ns element is inspired by [Schematron] and compliant to the requirements on namespace bindings described in [Tag Namespace Finding].

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.5: 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 ::= ns*, ( translateRule | locInfoRule | termRule | dirRule | rubyRule | langRule | withinTextRule )*
[3] rules.attributes ::= att.version.attributes, attribute xlink:href { xsd:anyURI }?
ns
[4] ns ::= element its:ns { ns.content, ns.attributes }
[5] ns.content ::= empty
[6] ns.attributes ::= attribute prefix { xsd:NCName }, attribute uri { xsd:anyURI }
att.selector
[7] att.selector.attributes ::= att.selector.attribute.selector
[8] att.selector.attribute.selector ::= attribute selector { string }
att.version
[9] att.version.attributes ::= att.version.attribute.version
[10] att.version.attribute.version ::= attribute its:version { xsd:float }

Go to the table of contents.5.3.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 wrapper for the local ITS attributes and ruby.

It depends on the data category what is being selected. The necessary data category specific defaults are described in Section 6.1: Position and Default Selections of Data Categories.

Example 14: Defaults for various data categories

its:translate="no" at the head element means that the textual content of this element, including child elements, should not be translated. its:translate="yes" at the body element means that the textual content of this element, including child elements, should be translated. Attribute values of the selected elements or their children's are not affected by local translate attributes. By default they are not translatable.

its:dir="ltr" at the body element means that the directionality of the textual content of this element, including child elements and attributes, is "left-to-right".

<text its:version="1.0">
 <head its:translate="no"> ... </head>
 <body its:translate="yes" its:dir="ltr"> ... </body>
</text>

[EX-selection-local-1.xml]

Markup for local selection is defined as follows.

span
[11] span ::= element its:span { span.content, span.attributes }
[12] span.content ::= ( text | ruby )*
[13] span.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes

Go to the table of contents.5.4 Link to External Rules

One way to associate a document with a set of external ITS rules is to use the optional XLink [XLink 1.0] href attribute in the rules element. The referenced document must be a valid XML document containing at most one rules element. That rules element can be the root element or anywhere within the document tree (for example, the document could be an XML Schema).

The rules contained in the referenced document MUST be processed as if they were at the top of the rules element with the XLink href attribute.

Example 15: External file myRules.xml with global rules:

The example demonstrates how metadata can be added to ITS rules.

<myFormatInfo>
 <desc>ITS rules used by the Open University</desc>
 <hostVoc>http://www.tei-c.org/ns/1.0</hostVoc>
 <rulesId>98ECED99DF63D511B1250008C784EFB1</rulesId>
 <rulesVersion>v 1.81 2006/03/28 07:43:21</rulesVersion> ...
 <its:rules its:version="1.0">
  <its:translateRule selector="//header" translate="no"/>
  <its:translateRule selector="//term" translate="no"/>
  <its:termRule selector="//term"/>
  <its:withinTextRule withinText="yes" selector="//term | //b"/>
 </its:rules>
</myFormatInfo>

[EX-link-external-rules-1.xml]

Example 16: Document with a link to myRules.xml
<myDoc>
 <header>
  <its:rules its:version="1.0" xlink:href="myRules.xml">
   <its:translateRule selector="//term" translate="yes"/>
  </its:rules>
  <author>Theo Brumble</author>
  <lastUpdate>Apr-01-2006</lastUpdate>
 </header>
 <body>
  <p>A <term>Palouse horse</term> has a spotted coat.</p>
 </body>
</myDoc>

[EX-link-external-rules-2.xml]

The result of processing the two documents above is the same as processing the following document.

Example 17: Document with identical rules as in the case of included rules
<myDoc>
 <header>
  <its:rules its:version="1.0">
   <its:translateRule selector="//header" translate="no"/>
   <its:translateRule selector="//term" translate="no"/>
   <its:termRule selector="//term"/>
   <its:withinTextRule withinText="yes" selector="//term | //b"/>
   <its:translateRule selector="//term" translate="yes"/>
  </its:rules>
  <author>Theo Brumble</author>
  <lastUpdate>Apr-01-2006</lastUpdate>
 </header>
 <body>
  <p>A <term>Palouse horse</term> has a spotted coat.</p>
 </body>
</myDoc>

[EX-link-external-rules-3.xml]

Application processing global ITS markup MUST recognize the XLink href attribute in the rules element; they MUST load the corresponding referenced document and process its rules element before processing the content of the rules element where the original XLink href attribute is.

External rules may also have links to other external rules. The linking mechanism is recursive, the deepest rules being overridden by the top-most rules, if any.

Go to the table of contents.5.5 Precedence between Selections

The following precedence order is defined for selections of ITS information in various positions (the first item in the list has the highest precedence):

  1. Implicit local selection in documents (ITS local attributes on a specific element)
  2. Global selections in documents (using a rules element)
  3. Global selections in an external file (using a rules element), linked via the XLink href attribute or a different mechanism
  4. Selections via defaults for data categories, see Section 6.1: Position and Default Selections of Data Categories

In case of conflicts between global selections via multiple rule elements, the last selector has higher precedence.

Note:

The precedence order fulfills the same purpose as the built-in template rules of [XSLT 1.0].

Example 18: Conflicts between selections of ITS information which are resolved using the precedence order

Due to the rules described above, the local translatability information from the translate attribute on the p element has precedence over the translatability information on the first translateRule element. A conflict occurs for p elements inside of entry elements, because of the two translateRule elements. This conflict is resolved via the order of the translateRule elements (the last one has higher precedence).

<text>
 <head>
  <its:rules its:version="1.0">
   <its:translateRule translate="yes" selector="//p"/>
   <its:translateRule translate="no" selector="//index/entry/p"/>
  </its:rules>
 </head>
 <body> ...
   <p its:translate="no"> ... </p>
 </body>
 <back>
  <index>
   <entry>
    <p> ... </p>
   </entry>
  </index>
 </back>
</text>

[EX-selection-precedence-1.xml]

Go to the table of contents.5.6 Associating ITS Data Categories with Existing Markup

Some markup schemes provide markup which can be used to express ITS data categories. ITS data categories can be associated with such existing markup, using the global selection mechanism described in Section 5.3.1: Global, Rule-based Selection. In this way, there is no need to integrate ITS markup into documents.

Associating existing markup with ITS data categories can be only done if the processing expectations are the same or if the processing expectations of the host markup cover at least the same as ITS.

Example 19: Association of the ITS data categories translatability and terminology with [DITA 1.0] markup
<topic id="myTopic">
 <title>The ITS Topic</title>
 <prolog>
  <its:rules its:version="1.0">
   <its:translateRule selector="//*[@translate='no']" translate="no"/>
   <its:translateRule selector="//*[@translate='yes']" translate="yes"/>
   <its:termRule selector="//term | //dt"/>
  </its:rules>
 </prolog>
 <body>
  <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>
  </dl>
  <p>For the implementation of ITS, apply the rules in the order:</p>
  <ul>
   <li>Defaults</li>
   <li>Rules in external files</li>
   <li>Rules in the document</li>
   <li>Local attributes</li>
  </ul>
  <p>
   <ph translate="no" xml:lang="fr">Et voilà !</ph>.</p>
 </body>
</topic>

[EX-associating-its-with-existing-markup-1.xml]

Go to the table of contents.6 Description of Data Categories

This section is normative.

Go to the table of contents.6.1 Position and Default Selections of Data Categories

The following table summarizes the relations between data categories, location of their selection mechanisms, and default selections in XML documents.

Data categoryLocal UsageGlobal, rule-based selectionGlobal adding of informationGlobal pointing to existing informationDefault selection in document
Translatability +++-Textual content of element, including content of child elements, but excluding attributes
Localization information ++++Textual content of element, including content of child elements, but excluding attributes
Terminology ++++Textual content of element, including content of child elements, but excluding attributes
Directionality +++-Textual content of element, including attributes and child elements
Ruby ++++Textual content of element, including content of child elements, but excluding attributes
Language Information -+-+Textual content of element, including attributes and child elements
Elements within Text -++-Textual content of element, excluding child elements

Note:

The data categories differ with respect to defaults in the XML document for compatibility reasons with existing standards and practices. For example, the dir attribute taken from [XHTML 2.0] refers to the content of the element and all attributes and child elements. Hence, the data category of directionality selects the same information as the default. On the other hand, it is common practice that information about translatability refers only to textual content of an element. Hence, the data category of translatability selects as a default the same information.

Go to the table of contents.6.2 Translatability

Go to the table of contents.6.2.1 Definition

The data category translatability 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).

Go to the table of contents.6.2.2 Implementation

Translatability can be expressed with global rules, or locally on an individual element.

As for global rules, translatability is expressed with a translateRule element with a translate attribute. The attribute has the values "yes" or "no". In addition, a selector attribute is required.

Example 20: Translatability expressed globally
<its:rules its:version="1.0">
 <its:translateRule translate="yes" selector="//p"/>
<!-- All p elements should be translated-->

</its:rules>

[EX-translate-selector-1.xml]

Locally, translatability is expressed with a translate attribute with the values "yes" or "no" The selection is the textual content of the element, including child elements, but excluding attributes.

Example 21: Translatability expressed locally

In the body element, its textual content and the content of all elements should be translated. The content of the specified quote element, however, must not be translated.

<book its:version="1.0">
 <head>...</head>
 <body its:translate="yes"> ...  
   <p>And he said: you need a new 
    <quote its:translate="no">motherboard</quote>
  </p> ...  </body>
</book>

[EX-translate-selector-2.xml]

Go to the table of contents.6.2.3 Markup Declarations for Translatability

translateRule
[14] translateRule ::= element its:translateRule { translateRule.content, translateRule.attributes }
[15] translateRule.content ::= empty
[16] translateRule.attributes ::= att.selector.attributes, attribute translate { "yes" | "no" }
att.translate
[17] att.translate.attributes ::= att.translate.attribute.translate
[18] att.translate.attribute.translate ::= attribute its:translate { "yes" | "no" }?

Go to the table of contents.6.3 Localization Information

Go to the table of contents.6.3.1 Definition

The data category localization information is used to communicate information to localizers about a particular item of content.

This data category has several purposes:

  • 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.

Go to the table of contents.6.3.2 Implementation

Localization information can be expressed with global rules, or locally on an individual element.

Using global rules, addition of localization information to selected nodes is achieved with a locInfoRule element, which has a mandatory selector attribute and a mandatory locInfoType attribute. The information associated to the selection can be indicated in different ways using either a locInfo element, a locInfoRef attribute, a locInfoPointer attribute, or a locInfoRefPointer attribute. The locInfo element, locInfoRef attribute, locInfoPointer attribute, and locInfoRefPointer MUST NOT occur together.

The locInfo element contains the information itself.

Example 22: The locInfo element
<myDoc>
 <head>
  <its:rules its:version="1.0">
   <its:locInfoRule locInfoType="alert" selector="/body/p[1]">
    <its:locInfo>This p element has to be handled carefully.</its:locInfo>
   </its:locInfoRule>
  </its:rules>
 </head>
 <body>
  <p>Paragraph to translate.</p>
 </body>
</myDoc>

[EX-locInfo-element-1.xml]

The locInfoRef attribute is an URI referring to the location of the information.

Example 23: The locInfoRef attribute
<myRes>
 <head>
  <its:rules its:version="1.0">
   <its:locInfoRule
     locInfoType="description"
     selector="/body/msg[@id='FileNotFound']"
     locInfoRef="ErrorsInfo.html/#FileNotFound"/>
  </its:rules>
 </head>
 <body>
  <msg id="FileNotFound">Cannot find the file {0}.</msg>
 </body>
</myRes>

[EX-locInfoRef-attribute-1.xml]

The locInfoPointer attribute is a relative XPath expression pointing to a node that holds the information.

Example 24: The locInfoPointer attribute
<Res>
 <prolog>
  <its:rules its:version="1.0">
   <its:locInfoRule
     locInfoType="description"
     selector="//msg/data"
     locInfoPointer="../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>

[EX-locInfoPointer-attribute-1.xml]

The locInfoRefPointer attribute contains a relative XPath expression pointing to a node that holds the URI referring to the location of the information.

Example 25: The locInfoRefPointer attribute
<data>
 <prolog>
  <its:rules its:version="1.0">
   <its:locInfoRule
     locInfoType="description"
     selector="//string"
     locInfoRefPointer="@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>
</data>

[EX-locInfoRefPointer-attribute-1.xml]

Locally in a document, localization information is expressed with the attributes locInfo or locInfoRef, and locInfoType. locInfo and locInfoRef MUST NOT occur together. If the locInfoType attribute is not present, the type of localization information will be assumed as description. The selection is the textual content of element, including child elements, but excluding attributes.

Example 26: Localization information expressed locally in a document
<book its:version="1.0">
 <head>...</head>
 <body> ...
   <p
    its:locInfo="This p element has to be handled carefully"
    its:locInfoType="alert">And he said: you need a new
     <quote>motherboard</quote>
  </p> ...
  </body>
</book>

[EX-locInfo-selector-2.xml]

Go to the table of contents.6.3.3 Markup Declarations for Localization Information

locInfoRule
[19] locInfoRule ::= element its:locInfoRule { locInfoRule.content, locInfoRule.attributes }
[20] locInfoRule.content ::= locInfo?
[21] locInfoRule.attributes ::= att.selector.attributes, attribute locInfoPointer { string }?, attribute locInfoType { "alert" | "description" }, attribute locInfoRef { xsd:anyURI }?, attribute locInfoRefPointer { string }?
locInfo
[22] locInfo ::= element its:locInfo { locInfo.content, locInfo.attributes }
[23] locInfo.content ::= text
[24] locInfo.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes
att.locInfo
[25] att.locInfo.attributes ::= att.locInfo.attribute.locInfo, att.locInfo.attribute.locInfoType, att.locInfo.attribute.locInfoRef
[26] att.locInfo.attribute.locInfo ::= attribute its:locInfo { string }?
[27] att.locInfo.attribute.locInfoType ::= attribute its:locInfoType { "alert" | "description" }?
[28] att.locInfo.attribute.locInfoRef ::= attribute its:locInfoRef { xsd:anyURI }?

Go to the table of contents.6.4 Terminology

Go to the table of contents.6.4.1 Definition

The terminology data category is used to mark terms. This helps to increase consistency across different parts of the documentation. It is also helpful for translation.

Go to the table of contents.6.4.2 Implementation

The terminology data category can be expressed with global rules, or locally on an individual element.

As for global rules, identifying terminology information at selected nodes is realized with a termRule element with a mandatory selector attribute. In addition, an optional termInfoRef attribute can be used to refer to external information about the term. The datatype of termInfoRef is xs:anyURI. To point to a link to a term reference in the current document, a termInfoRefPointer attribute can be used. termInfoRef and termInfoRefPointer MUST NOT be used together.

Example 27: Usage of the termInfoRefPointer attribute
<text> ...
 <its:rules its:version="1.0">
  <its:termRule selector="//term" 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>

[EX-terms-selector-1.xml]

Locally in a document, the terminology data category is expressed with a term attribute, which has the value "yes", and an optional termInfoRef attribute. The selection is the textual content of the element, including content of child elements, but excluding attributes.

Example 28: The terminology data category expressed in an instance document
<book its:version="1.0">
 <head>...</head>
 <body> ...  <p>And he said: you need a
   new <quote its:term="yes">motherboard</quote>
  </p> ...
  </body>
</book>

[EX-terms-selector-2.xml]

Go to the table of contents.6.4.3 Markup Declarations for Terminology

termRule
[29] termRule ::= element its:termRule { termRule.content, termRule.attributes }
[30] termRule.content ::= empty
[31] termRule.attributes ::= att.selector.attributes, attribute termInfoRef { xsd:anyURI }?, attribute termInfoRefPointer { string }?
att.term
[32] att.term.attributes ::= att.term.attribute.termInfoRef, att.term.attribute.term
[33] att.term.attribute.termInfoRef ::= attribute its:termInfoRef { xsd:anyURI }?
[34] att.term.attribute.term ::= attribute its:term { "yes" }?

Go to the table of contents.6.5 Directionality

Go to the table of contents.6.5.1 Definition

This data category expresses the directionality of a piece of text. Its values are "ltr", "rtl", "lro" or "rlo". This definition is compliant with the dir attribute in [XHTML 2.0], except that [XHTML 2.0] does not allow for rule-based, global selection. An implementation of the directionality data category MUST follow the XHTML family user agent conformance critera defined in that specification.

Go to the table of contents.6.5.2 Implementation

The dir attribute is used for the implementation of the directionality data category. It has the four values "ltr", "rtl", "lro" or "rlo".

Directionality can be expressed with global rules or locally on an individual element.

As for global rules, directionality is expressed in rules using a dirRule element with the dir attribute. In addition, a selector attribute is required.

Example 29: Directionality expressed with global rules
<its:rules its:version="1.0">
 <its:dirRule dir="rtl" selector="/body/p[1]/quote[xml:lang='he']"/>
<!-- Some Hebrew quotation -->

</its:rules>

[EX-dir-selector-1.xml]

Locally in a document, directionality is expressed with a dir attribute. The selection is the textual content of the element, including all child elements and attributes.

Example 30: Directionality expressed in an instance document
<book its:version="1.0">
 <head>...</head>
 <body> ...  <p>And he said: <quote its:dir="rtl"> ... a Hebrew quotation ... </quote>
  </p>
  ...  </body>
</book>

[EX-dir-selector-2.xml]

Go to the table of contents.6.5.3 Markup Declarations for Directionality

dirRule
[35] dirRule ::= element its:dirRule { dirRule.content, dirRule.attributes }
[36] dirRule.content ::= empty
[37] dirRule.attributes ::= att.selector.attributes, attribute dir { "ltr" | "rtl" | "lro" | "rlo" }
att.dir
[38] att.dir.attributes ::= att.dir.attribute.dir
[39] att.dir.attribute.dir ::= attribute its:dir { "ltr" | "rtl" | "lro" | "rlo" }?

Go to the table of contents.6.6 Ruby

Go to the table of contents.6.6.1 Definition

The data category ruby 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.

Go to the table of contents.6.6.2 Implementation

Ruby can be expressed locally in a document or with global rules.

Locally in a document, Ruby is realized with a ruby element.

Example 31: Ruby locally in a document
<text its:version="1.0">
 <head> ... </head>
 <body>
  <p>This is about the
      <its:ruby>
    <its:rb>W3C</its:rb>
    <its:rt>World Wide Web Consortium</its:rt>
   </its:ruby>
  </p>
 </body>
</text>

[EX-ruby-implementation-1.xml]

The structure of the content model for the ruby element is identical with the structure of ruby markup as defined in [Ruby-TR]. An implementation of the ruby data category MUST follow the conformance critera for ruby defined in that specification.

Note:

The structure of ruby defined in section 5.4 of [OpenDocument] is compliant with ruby defined in this specification.

The functionality of pointing to existing ruby markup is realized with various pointer attributes for ruby. There is a pointer attribute for the ruby element and each element within its content model.

Go to the table of contents.6.6.3 Handling Legacy Content

In legacy situations, where one cannot change the element markup and there one wants to apply ruby text to an attribute or existing element content, then the following approach can be used.

A rubyRule element can be used with two attributes:

  • A rubyText attribute contains the ruby text (corresponding to the rt element in the case of no selections)
  • A selector attribute contains the selector. It selects the ruby base text, corresponding to the rb element in the case of no selection.
Example 32: Adding ruby text with a rubyRule element
<text>
 <head> ... </head>
 <its:rules its:version="1.0">
  <its:rubyRule rubyText="World Wide Web Consortium" selector="/body/img[1]/@alt"/>
 </its:rules>
 <body>
  <img src="w3c_home.png" alt="W3C"/> ...
  </body>
</text>

[EX-ruby-legacy-1.xml]

Go to the table of contents.6.6.4 Markup Declarations for Ruby

rubyRule
[40] rubyRule ::= element its:rubyRule { rubyRule.content, rubyRule.attributes }
[41] rubyRule.content ::= empty
[42] rubyRule.attributes ::= att.selector.attributes, attribute rubyPointer { string }?, attribute rbPointer { string }?, attribute rtPointer { string }?, attribute rpPointer { string }?, attribute rbcPointer { string }?, attribute rtcPointer { string }?, attribute rubyText { string }?, attribute rbspanPointer { string }?
ruby
[43] ruby ::= element its:ruby { ruby.content, ruby.attributes }
[44] ruby.content ::= ( rb, ( rt | ( rp, rt, rp ) ) ) | ( rbc, rtc, rtc? )
[45] ruby.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes
rb
[46] rb ::= element its:rb { rb.content, rb.attributes }
[47] rb.content ::= text
[48] rb.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes
rt
[49] rt ::= element its:rt { rt.content, rt.attributes }
[50] rt.content ::= text
[51] rt.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes, attribute rbspan { string }?
rbc
[52] rbc ::= element its:rbc { rbc.content, rbc.attributes }
[53] rbc.content ::= rb+
[54] rbc.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes
rtc
[55] rtc ::= element its:rtc { rtc.content, rtc.attributes }
[56] rtc.content ::= rt+
[57] rtc.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes
rp
[58] rp ::= element its:rp { rp.content, rp.attributes }
[59] rp.content ::= text
[60] rp.attributes ::= att.translate.attributes, att.locInfo.attributes, att.term.attributes, att.dir.attributes

Go to the table of contents.6.7 Language Information

Go to the table of contents.6.7.1 Definition

The element langRule is used to express that a given piece of content (selected by the attribute langPointer) is used to express language information as defined by [RFC 3066bis].

Example 33: Pointing to language information via langRule

The following langRule element expresses that all p elements (including attributes and textual content of child elements) have a language value conformant to [RFC 3066bis]. The value is given by the mylangattribute attached to the p elements.

<its:rules its:version="1.0">
 <its:langRule selector="//p" langPointer="@mylangattribute"/>
</its:rules>

[EX-lang-definition-1.xml]

Go to the table of contents.6.7.2 Markup Declarations for Language Information

langRule
[61] langRule ::= element its:langRule { langRule.content, langRule.attributes }
[62] langRule.content ::= empty
[63] langRule.attributes ::= att.selector.attributes, attribute langPointer { string }

Go to the table of contents.6.8 Elements Within Text

Go to the table of contents.6.8.1 Definition

The data category elements within text expresses information about how elements should affect the flow of the content. In this context the flow of the content represents how the nodes of the elements should be treated as a single unit for linguistic purposes. Sometimes, a flow can be nested within another one. The values associated with this data category are:

  • "yes" (the element and its content are part of the flow of its parent element)
  • "nested" (the element is part of the flow of its parent element, its content is an independent flow)
  • "no" (the element splits the text flow of its parent element and its content is an independent text flow)

Elements not listed are considered to have the value "no".

Go to the table of contents.6.8.2 Implementation

This data category can be expressed only in a set of rules. It cannot be expressed as local markup on an individual element.

Element within text is expressed with a withinTextRule element with a withinText attribute. The attribute has the values "yes", "no" or "nested". In addition, a selector attribute is required.

Example 34: Elements within text
<its:rules its:version="1.0">
 <its:withinTextRule withinText="yes" selector="//b | //em | //i"/>
</its:rules>

[EX-within-text-implementation-1.xml]

Go to the table of contents.6.8.3 Markup Declarations for Elements within Text

withinTextRule
[64] withinTextRule ::= element its:withinTextRule { withinTextRule.content, withinTextRule.attributes }
[65] withinTextRule.content ::= empty
[66] withinTextRule.attributes ::= att.selector.attributes, attribute withinText { "yes" | "no" | "nested" }

Go to the table of contents.A Schemas for ITS (Non-Normative)

This section is informative.

The following schemas are provided:

Go to the table of contents.B Checking ITS Markup Constraints (Non-Normative)

This section is informative.

Several constraints of ITS markup cannot be validated with ITS schemas. The following [Schematron] document allows for validating some of these constraints.

Example 35: Testing constraints in ITS markup
<schema>
<!-- Schematron document to test constraints for global and local ITS markup.
 For ITS markup definitions, see http://www.w3.org/TR/its/ . -->

 <ns prefix="its" uri="http://www.w3.org/2005/11/its"/>
 <pattern
   name="Check ITS Global Rules and Local Constraints, and Version Constraints">
  <rule context="*">
<!-- Tests for locInfoRule -->

   <report
     test="name()='its:locInfoRule' and child::its:locInfo and @its:locInfoPointer">
   locInfoRule error: A locInfoRule element must not have both a locInfo child element
    and a locInfoPointer attribute.</report>
   <report
     test="name()='its:locInfoRule' and @its:locInfoRef and @its:locInfoRefPointer">
   locInfoRule error: A locInfoRule element must not have both a locInfoRef attribute
    and a locInfoRefPointer attribute.</report>
   <report
     test="name()='its:locInfoRule' and child::its:locInfo and @its:locInfoRef">
   locInfoRule error: A locInfoRule element must not have both a locInfo child element
   and a locInfoRef attribute.</report>
<!-- Test for termRule -->

   <report
     test="name()='its:termRule' and @its:termRef and @its:termRefPointer">
   termRule error: A termRule element must not have both a termRef attribute and a
   termRefPointer attribute.</report>
<!-- Test for rubyRule -->

   <report
     test="name()='its:rubyRule' and @its:rubyText and @its:rtPointer">
   rubyRule error: A rubyRule element must not have both a rubyText attribute and 
   a rtPointer attribute.</report>
<!-- Test for locInfo (local) -->

   <report
     test="@its:locInfo and @its:locInfoRef">
   Local ITS usage error: The locInfo attribute and the locInfoRef attribute
   must not be used together.</report>
<!-- Test for term (local) -->

   <report
     test="@its:termRef and not (@its:term[.='yes']) and not(name()='its:termRule')">
   Local ITS usage error: A termRef attribute must not appear locally without
   a term attribute which has the value 'yes'.</report>
<!-- Version attribute test -->

   <report
     test="/*/@its:version != @its:version">
   The version attribute at the root element and at the rules element
   must not specify different versions of ITS.</report>
  </rule>
 </pattern>
</schema>

[its-constraints-check-schematron.xml]

Go to the table of contents.C References

QAFRAMEWORK
Karl Dubost, Lynne Rosental, Dominique Hazaël-Massieux, Lofton Henderson. QA Framework: Specification Guidelines. W3C Recommendation 17 August 2005. Available at http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/. The latest version of QAFRAMEWORK is available at http://www.w3.org/TR/qaframe-spec/.
RELAX NG
James Clark, Makoto Murata. RELAX NG Specification. OASIS Committee Specification 3 December 2001. Available at http://www.oasis-open.org/committees/relax-ng/spec-20011203.html. The latest version of RELAX NG is available at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=relax-ng.
RFC 2119
S. Bradner. Key Words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119. Available at http://www.ietf.org/rfc/rfc2119.txt.
RFC 3066bis
Addison Phillips, Mark Davis. Tags for the Identification of Languages. IETF Internet-Draft, October 2005. See http://www.ietf.org/internet-drafts/draft-ietf-ltru-registry-14.txt.
Ruby-TR
Marcin Sawicki (until 10 October, 1999), Michel Suignard, Masayasu Ishikawa (石川 雅康), Martin Dürst, Tex Texin, Ruby Annotation. W3C Recommendation 31 May 2001. Available at http://www.w3.org/TR/2001/REC-ruby-20010531/ . The latest version of Ruby Annotation is available at http://www.w3.org/TR/ruby/.
XHTML 2.0
Jonny Axelsson, Mark Birbeck, Micah Dubinko, Beth Epperson, Masayasu Ishikawa, Shane McCarron, Ann Navarro, Steven Pemperton. XHTML™ 2.0. W3C Working Draft 27 May 2005. Available at http://www.w3.org/TR/2005/WD-xhtml2-20050527/. The latest version of XHTML 2.0 is available at http://www.w3.org/TR/xhtml2.
XLink 1.0
Steve DeRose, Eve Maler, David Orchard. XML Linking Language 1.0. W3C Recommendation 27 June 2001. Available at http://www.w3.org/TR/2001/REC-xlink-20010627/. The latest version of XLink 1.0 is available at http://www.w3.org/TR/xlink/.
XML 1.0
Tim Bray, Jean Paoli, C.M. Sperberg-McQueen, et al., editors. Extensible Markup Language (XML) 1.0 (Third Edition), W3C Recommendation 04 February 2004. Available at http://www.w3.org/TR/2004/REC-xml-20040204/. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml/.
XML Infoset
John Cowan, Richard Tobin. XML Information Set (Second Edition). W3C Recommendation 4 February 2004. Available at http://www.w3.org/TR/2004/REC-xml-infoset-20040204/. The latest version of XML Infoset is available at http://www.w3.org/TR/xml-infoset/.
XML Names
Tim Bray, Dave Hollander, Andrew Layman. Namespaces in XML. W3C Recommendation 14 January 1999. Available at http://www.w3.org/TR/1999/REC-xml-names-19990114/. The latest version of XML Names is available at http://www.w3.org/TR/REC-xml-names/.
XML Schema
Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn. XML Schema Part 1: Structures Second Edition. W3C Recommendation 28 October 2004. Available at http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/. The latest version of XML Schema is available at http://www.w3.org/TR/xmlschema-1/.
XPath 1.0
James Clark. XML Path Language (XPath) Version 1.0. W3C Recommendation 16 November 1999. Available at http://www.w3.org/TR/1999/REC-xpath-19991116. The latest version of XPath 1.0 is available at http://www.w3.org/TR/xpath.

Go to the table of contents.D References (Non-Normative)

CSS2
Cascading Style Sheets, level 2. W3C Recommendation 12 May 1998. Available at http://www.w3.org/TR/1998/REC-CSS2-19980512. The latest version of CSS2 is available at http://www.w3.org/TR/REC-CSS2/.
DITA 1.0
Michael Priestley, JoAnn Hackos, et. al., editors. OASIS Darwin Information Typing Architecture (DITA) Language Specification v1.0. OASIS Standard 9 May 2005. Available at http://www.oasis-open.org/committees/download.php/15316/dita10.zip.
DocBook
Norman Walsh and Leonard Muellner. DocBook: The Definitive Guide. Available at http://www.docbook.org/.
l10n i18n
Richard Ishida, Susan Miller. Localization vs. Internationalization. Article of the W3C Internationalization Activity, January 2006.
ITS REQ
Yves Savourel. Internationalization and Localization Markup Requirements. W3C Working Draft 18 May 2006. Available at http://www.w3.org/TR/2006/WD-itsreq-20060518/. The latest version of ITS REQ is available at http://www.w3.org/TR/itsreq/.
OpenDocument
Michael Brauer et al. OASIS Open Document Format for Office Applications (OpenDocument).. Oasis Standard 1 May 2005. Available at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office. The latest version of OpenDocument is available at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office.
Schematron
Schematron - A Language for Making Assertions about Patterns Found in XML Documents. Available at http://www.schematron.com/.
Tag Namespace Finding
Norman Walsh. Using Qualified Names (QNames) as Identifiers in XML Content. TAG Finding 17 March 2004. Available at http://www.w3.org/2001/tag/doc/qnameids.html.
TEI
Lou Burnard and Syd Bauman (eds). Text Encoding Initiative Guidelines development version (P5). TEI Consortium, Charlottesville, Virginia, USA, Text Encoding Initiative.
XHTML 1.0
Steven Pemperton et al. XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition). W3C Recommendation 26 January 2000, revised 1 August 2002. Available at http://www.w3.org/TR/2002/REC-xhtml1-20020801/. The latest version of XHTML 1.0 is available at http://www.w3.org/TR/xhtml1/.
XML i18n BP
Yves Savourel, Diane Stoick. Best Practices for XML Internationalization. Available at http://www.w3.org/TR/2006/WD-xml-i18n-bp-20060518/. The latest version of xml-i18n-bp is available at http://www.w3.org/TR/xml-i18n-bp/.
XMLSPEC
The XML Spec Schema and Stylesheets. Available at http://www.w3.org/2002/xmlspec/.
XSLT 1.0
James Clark. XSL Transformations (XSLT) Version 1.0. W3C Recommendation 16 November 1999. Available at http://www.w3.org/TR/1999/REC-xslt-19991116. The latest version of XSLT 1.0 is available at http://www.w3.org/TR/xslt.
XUL
exTensible User Inferface Language. Available at http://www.xulplanet.com/.

Go to the table of contents.E Revision Log (Non-Normative)

The following log records major changes that have been made to this document since the publication in November 2005.

  1. A section about basic concepts of ITS has been created.
  2. Terminology has been modified: the terms for position of ITS information in situ versus dislocated have been replaced by selection in an instance document versus global, rule-based selection.
  3. The definition of the directionality data category has been changed, to be compliant to various other specifications. See the comment on bidirectionality for further information.
  4. Terminology within the text of this document and within the markup declarations has been modified: scope of ITS information has been replaced with selection of ITS information.
  5. The schemaRules element has been removed. For ITS information as schema annotation, where is now only a schemaRule element.
  6. All ITS attributes are now defined as qualified attributes. This leads to changes in the generated ITS schemas, for example the generation of parameter entities for prefixes in the XML DTD. This allows for easy changing of prefixes in element or attribute names.
  7. The possibility of selector attributes in instance documents (in the previous draft this was called scope in an instance document) has been removed. Local selection in an instance document now relies only on default selections of data categories. Due to this change, the definition of precedence between selections and conformance criteria have been simplified, and the issue on namespace requirements and selector values could be resolved.
  8. Definitions of default selections of data categories have been modified.
  9. An ns element has been added to the rules element to allow for specifying namespace bindings.
  10. The implementation of the ruby data category has been modified, to reflect the removal of selector attributes in instance documents.
  11. A section on mapping of ITS data categories to existing markup has been created.
  12. Examples of integrating ITS markup into a TEI schema and into XML Spec have been created.
  13. A span element has been created.
  14. The examples have been modified to reflect changes mentioned above.
  15. For clarity, various sections have been reworded and re-structured, and the visualization of ITS markup within the text of this document has been modified.
  16. Tracking of issues is now handled via Bugzilla.
  17. A revision log has been added.

The following log records major changes that have been made to this document since the publication in February 2006.

  1. The schemaRule element, and the notion of schema annotation which was connected to it, have been abandoned.
  2. The section on conformance has been rewritten and placed at the beginning of the document.
  3. In global rules, the documentRule element has been replaced with elements which have data category specific names. This eases the creation and validation of global rules.
  4. In global rules, instead of rule specific attributes for selection, there is now just one selector attribute.
  5. In global rules, the documentRules element has been renamed to rules.
  6. In global rules, in addition to the existing functionality of adding ITS information to selected nodes, a new functionality of pointing to information in an XML document has been created.
  7. An XLink href attribute has been added to the rules element to allow for links to external rules. The precedence between selections has been modified to reflect this change.
  8. Two new data categories language information and elements within text have been defined.
  9. The data category ruby has been redefined, to be conforming to [Ruby-TR].
  10. The declarations for ITS markup have been rewritten, to adopt the changes mentioned above.
  11. The declarations for ITS markup (formally all assembled in a single section) have been separated and placed in the sections there they are described.
  12. A modularization of ITS and XHTML 1.0 has been created.
  13. The informative Section 1: Introduction and Section 2: Basic Concepts have been rewritten.
  14. Examples and the modularizations of ITS with existing markup schemes have been changed to reflect the modifications mentioned above.

The following log records major changes that have been made to this document since the publication in April 2006.

  1. The conformance section has been rewritten.
  2. The terminology of mapping ITS data categories with existing markup has been changed to associating ITS Data Categories with existing markup.
  3. The global rule elements have been rewritten to have attributes in the empty namespace.
  4. The examples have been validated, partially modified and extended.
  5. Documentation strings have been added to elements and attributes.
  6. The data category elements within text has been redefined.
  7. Clarifications about ITS and inclusion mechanisms and selections of pointers to external (possibly non-textual) objects have been made.
  8. The local attributes have been reorganised into various data category specific groups.
  9. A versioning mechanism has been introduced
  10. A summary of ITS markup has been created.
  11. The automatically generated ITS schemas have been augmented with element and attribute documentations.
  12. A description of ITS markup constraints not covered by the ITS schemas has been created.
  13. The attributes termRef and termRefPointer have been renamed to termInfoRef and termInfoRefPointer.
  14. A list of requirements which are formulated in [ITS REQ], but not covered in this document, has been created. See Section 1: Introduction.

Go to the table of contents.F Acknowledgements (Non-Normative)

This document has been developed with contributions by the ITS Working Group. At the date of publication, the members of the Working Group were: Damien Donlon (Sun Microsystems), Martin Dürst (Invited Expert), Richard Ishida (W3C), Masaki Itagaki (Invited Expert), Christian Lieske (SAP AG), Naoyuki Nomura (Ricoh), Sebastian Rahtz (Invited Expert), François Richard (HP), Goutam Saha (CDAC), Felix Sasaki (W3C), Yves Savourel (ENLASO), Dianne Stoick (Boeing), Najib Tounsi (Ecole Mohammadia d'Ingénieurs Rabat (EMI)) and Andrzej Zydroń (Invited Expert).

A special thanks goes to Sebastian Rahtz who introduced us to the ODD language, which was used to create this document, and who provided the stylesheets to generate schemas and the XHTML version out of an ODD document. The generation of XHTML from ODD takes an intermediate step through the xmlspec-i18n.dtd.

$Id: itstagset.odd,v 1.124 2006/04/20 14:24:12 fsasaki Exp $