Best Practices for XML Internationalization [ contents This version: http://www.w3.org/TR/2008/NOTE-xml-i18n-bp-20080213/ Latest version: http://www.w3.org/TR/xml-i18n-bp/ Previous version: http://www.w3.org/TR/2007/WD-xml-i18n-bp-20071031/ Editors: Yves Savourel, ENLASO Corporation Jirka Kosek, Invited Expert Richard Ishida, W3C This document is also available in these non-normative formats: PDF version XHTML Diff markup to publication from 31 October 2007 Copyright W3C ® MIT ERCIM Keio liability trademark document use This document provides a set of guidelines for developing XML documents and schemas that are internationalized properly. Following the best practices describes here allow both the developer of XML applications, as well as the author of XML content to create material in different languages. 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 W3C Working Group Note Best Practices for XML Internationalization Internationalization Tag Set (ITS) Working Group W3C Internationalization Activity Feedback about this document is encouraged. Send your comments to [email protected] archives Publication as a Working Group Note 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 public list of any patent disclosures Essential Claim(s) section 6 of the W3C Patent Policy 1 Introduction 1.1 Who should use this document 1.2 How to use this document 1.2.1 Designers and developers of XML applications 1.2.2 Users and authors of XML content 2 When Designing an XML Application Best Practice 1: Defining markup for natural language labelling Best Practice 2: Defining markup to specify text direction Best Practice 3: Avoiding translatable attribute values Best Practice 4: Indicating which elements and attributes should be translated Best Practice 5: Defining markup to override translate information Best Practice 6: Providing information related to text segmentation Best Practice 7: Defining markup for ruby text Best Practice 8: Defining markup for notes to localizers Best Practice 9: Defining markup for unique identifiers Best Practice 10: Identifying terminology-related elements Best Practice 11: Defining markup for specifying or overriding terminology-related information Best Practice 12: Working with multilingual documents Best Practice 13: Naming elements and attributes Best Practice 14: Defining a span-like element Best Practice 15: Documenting internationalization and localization features of your schema 3 When Authoring XML Content Best Practice 16: Specifying the language of content Best Practice 17: Specifying text directionality Best Practice 18: Overriding information about what should be translated Best Practice 19: Assigning unique identifiers Best Practice 20: Avoiding CDATA sections Best Practice 21: Providing notes for localizers Best Practice 22: Working with inserted text Best Practice 23: Identifying terms Best Practice 24: Storing markup from another format 4 Generic Techniques 4.1 Writing ITS Rules 4.1.1 Precedence and Inheritance 4.1.2 Dealing with namespaces 4.1.3 Create your XPath expressions with care 4.2 Example of adding an attribute to an existing schema 4.2.1 Including xml:lang in XML Schema 4.2.2 Including xml:lang in RELAX NG 4.2.3 Including xml:lang in an XML DTD 5 ITS Applied to Existing Formats 5.1 ITS and XHTML 1.0 5.1.1 Integrating ITS into XHTML 5.1.2 Using XHTML Modularization 1.1 for the Definition of ITS 5.1.3 Using NVDL to integrate ITS into XHTML 5.1.4 Associating existing XHTML markup with ITS 5.2 ITS and TEI 5.2.1 Integrating ITS into TEI 5.3 ITS and XML Spec 5.3.1 Integration of ITS into XML Spec 5.3.2 Associating existing XML Spec markup with ITS 5.4 ITS and DITA 5.4.1 Integration of ITS into DITA 5.4.2 Associating existing DITA markup with ITS 5.5 ITS and GladeXML 5.5.1 Integration of ITS into GladeXML 5.5.2 Associating Existing GladeXML Markup with ITS 5.6 ITS and DocBook 5.6.1 Integration of ITS into DocBook 5.6.2 Associating existing DocBook markup with ITS A References B Acknowledgements This document is a complement to the W3C Recommendation Internationalization Tag Set (ITS) Version 1.0 [ITS] This document and Internationalization Tag Set (ITS) Version 1.0 [ITS] Internationalization and Localization Markup Requirements [ITS REQ] This set of best practices does not cover all topics about internationalization for XML. Other useful reference material includes: Character Model for the World Wide Web 1.0: Fundamentals [CharMod] Unicode in XML and other Markup Languages [Unicode in XML] This document is divided into two main sections: The first one is intended for the designers and developers of XML applications (also referred to here as ' schemas formats The second is intended for the XML content authors Section 2: When Designing an XML Application Section 4: Generic Techniques Section 5: ITS Applied to Existing Formats Section 3: When Authoring XML Content Section 4.1: Writing ITS Rules Designers and developers of XML applications should take into account the following best practices: Best Practice Implementing as a new feature Handling legacy markup Defining markup for natural language labelling Make sure the xml:lang Provide an ITS Rules document its:langRule xml:lang Defining markup to specify text direction Make sure the its:dir Provide an ITS Rules document its:dirRule Avoiding translatable attribute values Make sure you store all translatable text as element content, not as attribute values. Provide an ITS Rules document its:translateRule Indicating which elements and attributes should be translated Provide an ITS Rules document its:translateRule Defining markup to override translate information Make sure the its:translate It is also recommended that you define the its:rules its:translateRule Provide an ITS Rules document its:translateRule ITS Translate data category Providing information related to text segmentation Provide an ITS Rules document its:withinTextRule Defining markup for ruby text Make sure the its:ruby Provide an ITS Rules document its:rubyRule Defining markup for notes to localizers Make sure the attributes its:locNote its:locNoteType its:locNoteRef its:locNote its:locNoteRef It is also recommended that you define the its:rules its:locNoteRule its:locNoteRule its:locNote Provide an ITS Rules document its:locNoteRule Defining markup for unique identifiers Make sure that elements with translatable content can be associated with a unique identifier. Identifying terminology-related elements Provide an ITS Rules document its:termRule Defining markup for specifying or overriding terminology-related information Make sure the its:term its:termInfoRef It is also recommended to define the its:rules its:rules its:termRule Working with multilingual documents For documents that need to go through some localization tasks, always store the localized version of the text in a separate document. Naming elements and attributes Make sure the names of the elements and attributes of your schema reflect their functions, rather than one possible way of rendering their content. Also, if possible, avoid element names which do not follow a fixed naming scheme (for example, element names that serve also as identifiers). Not applicable Defining a span-like element Make sure you define a span If no span its:span Documenting internationalization and localization features of your schema Make sure you document the internationalization and localization aspects of your schema by providing a set of relevant ITS rules in a single standalone ITS Rules document. Where it says "How to implement this as a new feature", this section describes how to create new schemas or add new features to existing schemas. When doing this you may need to take into account the following: Think twice before creating your own schema. Seriously consider using existing formats such as DITA Check carefully whether an existing format comes with a built-in capability for modification. DocBook and DITA, for example, come with their own set of features for adapting their format to special needs. The modification mechanisms available will depend on the schema language (DTD, XML Schema, RELAX NG, etc.) For example, namespace-based modularization of schemas is difficult to achieve with DTDs. NVDL Each schema language provides different ways of extending or modifying existing schemas. Some examples are the include import redefine Some processors do not implement support for all schema language constructs, due to erroneous implementations or differences in conformance profiles (e.g. see the conformance requirements to XML Schema part 1 What is possible also depends on the features of the schema which the modification is targeting. For example: An XML Schema redefine If you are working with XML Schema, you can only apply the technique of ' chameleon proxy http://www.xfront.com/ZeroOneOrManyNamespaces.html chameleon XML Schema document for ITS chameleon Note: Best Practice 1: Defining markup for natural language labelling Provide a way for authors to specify the natural language of content using ITS markup, or document equivalent legacy markup in an ITS Rules document. The XML namespace provides the xml:lang ITS Language Information data category its:langRule How to implement this as a new feature Make sure the xml:lang For examples of how to add attributes in your existing schema see Section 4.2: Example of adding an attribute to an existing schema Some XML documents may be designed to store data without natural language content. In these cases, there is no need for the xml:lang The scope of the xml:lang avoid translatable attributes Make sure that the definition of the xml:lang In a DTD you must not use NMTOKEN CDATA In XML Schema the built-in data type language xml:lang http://www.w3.org/2001/xml.xsd It is not recommended xml:lang lang() Note: xml:lang xml:lang in XML document schemas In XHTML the language of a file linked with the a hreflang a <a xml:lang="en" href="german.html" hreflang="de">Click here for German</a> If you have different languages in the attribute values and content of an element, consider nesting elements, if possible. See Handling attribute values and element content in different languages Handling markup not in the ITS namespace If you are working with an existing schema where there is a way to specify content language that uses something other than the xml:lang xml:lang provide an ITS Rules document its:langRule xml:lang In this document the langcode text langcode xml:lang Note: Best Practice 12: Working with multilingual documents <myRes> <messages> <msg id="1"> <langcode>en</langcode> <text>Cannot find file.</text> </msg> <msg id="2"> <langcode>fr</langcode> <text>Fichier non trouvé.</text> </msg> </messages> </myRes> [ Example's source code The corresponding ITS Rules document contains an its:langRule langcode xml:lang text <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:langRule selector="//text[../langcode]" langPointer="../langcode"/> </its:rules> [ Example's source code Why do this Information about the language of content can be very important for correctly rendering or styling text in some scripts, applying spell-checkers during content authoring, appropriate selection of voice for text-to-speech systems, script-based processing, and numerous other reasons. You must provide a standard way to specify the language for the document as a whole, but also for parts of the document where the language changes. Resources: Background information Internationalization FAQ: xml:lang in XML document schemas. http://www.w3.org/International/questions/qa-when-xmllang Mechanisms for declaring language in HTML http://www.w3.org/TR/i18n-html-tech-lang/#ri20050208.095812479 Reference links Description of the language identification mechanism in the XML specification. http://www.w3.org/TR/REC-xml/#sec-lang-tag The "Language Information" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#language-information More resources Technique index Topic index Best Practice 2: Defining markup to specify text direction Provide a way for authors to specify the direction of text using ITS markup, or document equivalent legacy markup in an ITS Rules document. In scripts such as Arabic and Hebrew characters may run from both left to right and right to left when displayed. Directional markup allows you to manage the flow of characters. For an example of how directional markup is used see Creating (X)HTML Pages in Arabic & Hebrew The ITS Directionality data category its:dir its:dirRule How to implement this as a new feature Make sure the its:dir For examples of how to add attributes in your existing schema see Section 4.2: Example of adding an attribute to an existing schema Handling markup not in the ITS namespace If you are working with an existing schema where there is a way to specify text directionality that is not implemented using the its:dir provide an ITS Rules document its:dirRule In this document the textdir <text xml:lang <body> <par> <quote xml:lang textdir פעילות הבינאום, W3C </quote <quote> </quote </par </body </text Note: Problems with bidirectional source text [Bidi in X/HTML] [ Example's source code The corresponding ITS Rules document contains a set of its:dirRule textdir ITS Directionality data category <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:dirRule selector="//*[@textdir='l2r']" dir="ltr"/> <its:dirRule selector="//*[@textdir='r2l']" dir="rtl"/> <its:dirRule selector="//*[@textdir='lro']" dir="lro"/> <its:dirRule selector="//*[@textdir='rlo']" dir="rlo"/> </its:rules> [ Example's source code Why do this Generally the Unicode bidirectional algorithm will produce the correct ordering of mixed directionality text in scripts such as Arabic and Hebrew. Sometimes, however, additional help is needed. For instance, in the sentence of Example 4 The following will display incorrectly, since no directional markup has been used: The title says " פעילות הבינאום, W3C The text 'W3C' and the comma should be to the left of the quoted Hebrew text. If your browser supports bidirectional display, the following should appear correctly, since directional markup has been added to the element surrounding the quote: The title says " פעילות הבינאום, W3C The desired effect can be achieved using Unicode control characters, but this is not recommended (See Unicode in XML and other Markup Languages [Unicode in XML] Markup is also occasionally needed to disable the effects of the bidirectional algorithm for a specified range of text. Resources: Background information Internationalization FAQ: What you need to know about the bidi algorithm and inline markup http://www.w3.org/International/articles/inline-bidi-markup/ Authoring Techniques for XHTML & HTML Internationalization: Handling Bidirectional Text 1.0 http://www.w3.org/TR/i18n-html-tech-bidi/#ri20030728.094313871 Unicode Technical Report #20: Unicode in XML and other Markup Languages http://www.w3.org/TR/2007/NOTE-unicode-xml-20070516/ Reference links The "Directionality" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#directionality More resources Technique index Topic index Best Practice 3: Avoiding translatable attribute values Do not define attribute values that will contain user readable content. Use elements for such content. How to implement this as a new feature Make sure you store all translatable text as element content, not as attribute values. It is bad design to use the desc image <image src="elephants.png" desc="Elephants bathing in the Zambezi River."/> Instead, define the content of image <image src="elephants.png">Elephants bathing in the Zambezi River.</image> Note: Example 5 image Best Practice 6: Providing information related to text segmentation Handling markup not in the ITS namespace If you are working with an existing schema where there are attributes with translatable values, you should provide an ITS Rules document its:translateRule Best Practice 4: Indicating which elements and attributes should be translated Why do this There are a number of issues related to storing translatable text in attribute values. Some of them are: The language identification mechanism (i.e. xml:lang It may be necessary to apply some language-related properties, such as directionality and language identification, to only part of the text in an attribute value. This requires the use of a span It is difficult to apply meta-information, such as no-translate flags, author's notes, etc., to the text of an attribute value The difficulty of attaching unique identifiers to translatable attribute text makes it more complicated to use ID-based leveraging tools. It can be problematic to prepare translatable attributes for localization because they can occur within the content of a translatable element, breaking it into different parts, and possibly altering the sentence structure. All these potential problems are less likely to occur when the text is the content of an element rather than the value of an attribute. Resources: Background information "Attributes and translatable text" in "Requirements for Localizable DTD Design" http://people.w3.org/rishida/localizable-dtds/#attributes Reference links The "Translate" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat The "Element Within Text" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#elements-within-text More resources Technique index Topic index Best Practice 4: Indicating which elements and attributes should be translated Document in an ITS Rules document which elements and attributes need to be translated, and which do not, when this differs from the ITS defaults. The ITS Translate data category its:translateRule How to do this Provide an ITS Rules document its:translateRule If you are working with a schema where there are translatable attributes ( something that is not recommended its:translateRule Note: xml:lang="zxx" zxx In the following document, the content of the head alt del <myDoc xml:lang='en'> <head> <id xml:lang="zxx">H4-A3-F8-A1</id> <author>Robert Griphook</author> <rev>v13 2007-10-27</rev> </head> <par>To start click <ins>the <ui>Start</ui> button</ins><del>green icon</del> and fill the form labeled by the following icon: <ref file="vat.png" alt="Value Added Tax Form"/></par> </myDoc> [ Example's source code The following rules specify exceptions from the default ITS behavior for documents like the one above. <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:translateRule selector="/myDoc/head" translate="no"/> <its:translateRule selector="//*/@alt" translate="yes"/> <its:translateRule selector="//del" translate="no" /> <its:translateRule selector="//@*[ancestor::del]" translate="no"/> <its:translateRule selector="//*[lang('zxx')] | //@*[lang('zxx')]" translate="no"/> </its:rules> First translateRule head myDoc head Second translateRule alt Third translateRule del Fourth translateRule del Fifth translateRule zxx [ Example's source code Why do this By default, ITS assumes that the content of all elements is translatable and that all attributes have non-translatable values. If your XML document type does not correspond to this default assumption it is important to indicate what are the exceptions. Doing so can significantly improve translation throughput. Resources: Reference links The "Translate" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat More resources Technique index Topic index Best Practice 5: Defining markup to override translate information Provide a way for authors to override translate defaults, using ITS markup, or document equivalent legacy markup in an ITS Rules document. The ITS Translate data category its:translate its:translateRule How to implement this as a new feature Make sure the its:translate For examples of how to add attributes in your existing schema see Section 4.2: Example of adding an attribute to an existing schema It is also recommended that you define the its:rules its:translateRule Handling markup not in the ITS namespace If you are working with a schema where there is a way to override translate information that is not its:translate provide an ITS Rules document its:translateRule ITS Translate data category For example, DITA offers a translate Glade translatable its:translate The following rules indicate how to associate the DITA translate ITS Translate data category First translateRule translate no Second translateRule translate no translate="no" Third translateRule translate yes translate="yes" translate="no" <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:translateRule selector="//*[@translate='no']" translate="no"/> <its:translateRule selector="//*[@translate='no']/descendant-or-self::*/@*" translate="no"/> <its:translateRule selector="//*[@translate='yes']" translate="yes"/> </its:rules> [ Example's source code You can find a more complete example of how DITA markup is associated with ITS in Section 5.4.2: Associating existing DITA markup with ITS Why do this In some cases, the author of a document may need to change the translatability property on parts of the content, overriding ITS default behavior, or the general rules for the schema that you have specified when applying Best Practice 4: Indicating which elements and attributes should be translated Resources: Reference links The "Translate" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#trans-datacat More resources Technique index Topic index Best Practice 6: Providing information related to text segmentation Document in an ITS Rules document how elements should be handled with regard to segmentation. Segmentation refers to how text is broken down, from a linguistic viewpoint, into units that can be handled by processes such as translation. The ITS Element Within Text data category its:withinTextRule How to do this Whether you are creating a new schema or documenting legacy markup, provide an ITS Rules document its:withinTextRule In the following DITA document: The elements term b The element fn <concept id="myConcept" xml:lang="en-us"> <title>Types of horse</title> <conbody> <ol> <li>Palouse horse:<p><term>Palouse horses</term><fn>A palouse horse is the same as an <b>Appaloosa</b>.</fn> have spotted coats. The <term>Nez-Perce</term> Indians have been key in breeding this type of horse.</p></li> </ol> </conbody> </concept> [ Example's source code The its:withinTextRule its:withinText="no" First withinTextRule term b Second withinTextRule fn <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:withinTextRule selector="//term | //b" withinText="yes"/> <its:withinTextRule selector="//fn" withinText="nested"/> </its:rules> These rules applied to the DITA document above will result in four distinct runs of text: title: "Types of horse" li: "Palouse horse:" p: "{term}Palouse horses{/term}{fn/} have spotted coats. The {term}Nez-Perce{/term} Indians have been key in breeding this type of horse." fn: "A palouse horse is the same as an {b}Appaloosa{/b}." [ Example's source code Why do this Many applications that process content for linguistic-related tasks need to be able to perform a basic segmentation of the text content. They need to be able to do this without knowing the semantics of the elements. While in many cases it is possible to detect mixed content automatically, there are some situations where the structure of an element makes it impossible for tools to know for sure where appropriate segmentation boundaries fall. For example, the boundaries of some inline elements, such as emphasis, do not typically correspond to segmentation boundaries; on the other hand, some inline elements embedded in a parent element, such as footnotes or quotations, may define segments that should be handled separately from the text in which they are embedded. Intelligent segmentation is particularly important in translation to successfully match source text against translation-memory databases. Resources: Reference links The "Element Within Text" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#elements-within-text More resources Technique index Topic index Best Practice 7: Defining markup for ruby text Provide a way for authors to mark up ruby text using ITS markup, or document equivalent legacy markup in an ITS Rules document. Ruby text is used to provide a short annotation of an associated base text. It is most often used to provide a reading (pronunciation) guide. The ITS Ruby data category its:ruby its:rubyRule [Ruby Annotation] How to implement this as a new feature Make sure the its:ruby Handling markup not in the ITS namespace If you are working with an existing schema where there is a way to specify ruby text that has the same semantics as the ITS Ruby data category Ruby Annotation [Ruby Annotation] provide an ITS Rules document its:rubyRule In this document, the rubyBlock its:ruby rBase its:rb rParen its:rp rText its:rt <text> <para>この本は <rubyBlock> <rBase>慶応義塾大学</rBase> <rParen>(</rParen> <rText>けいおうぎじゅくだいがく</rText> <rParen>)</rParen> </rubyBlock>の歴史を説明するものです。</para> </text> [ Example's source code This its:rubyRule rBase its:rb its:ruby its:rt its:rt <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:rubyRule selector="//rBase" rubyPointer=".." rpPointer="../rParen" rtPointer="../rText" /> </its:rules> [ Example's source code Why do this Ruby is a type of annotation for text. It can be used with any language, but is very commonly used with East Asian scripts to provide phonetic transcriptions of characters that are likely to be unfamiliar to a reader. For example it is widely used in educational materials and children’s texts. It is also occasionally used to convey information about meaning. Because ruby annotation may be needed when localizing into Japanese or Chinese, it is a good idea to make provision for it in your schema, even if your original documents are to be developed into a language that does not use such markup. Resources: Background information Internationalization FAQ: Ruby http://www.w3.org/International/questions/qa-ruby "Implementing the Ruby Module", a personal note. http://www.w3.org/People/mimasa/test/schemas/NOTE-ruby-implementation Reference links The "Ruby" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#ruby-annotation Ruby Annotation http://www.w3.org/TR/ruby/ More resources Technique index Topic index Best Practice 8: Defining markup for notes to localizers Provide a way for authors to specify notes for localizers using ITS markup, or document equivalent legacy markup in an ITS Rules document. The ITS Localization Note data category its:locNote its:locNoteType its:locNoteRef its:locNoteRule How to implement this as a new feature Make sure the attributes its:locNote its:locNoteType its:locNoteRef its:locNote its:locNoteRef For examples of how to add attributes in your existing schema see Section 4.2: Example of adding an attribute to an existing schema its:locNoteRef The its:locNote NotFound its:locNoteRef <myRes> <head> <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:locNoteRule locNoteType="description" selector="//msg[@id='NotFound']" locNoteRef="EX-devlocnotes-4.html#NotFound" /> </its:rules> </head> <body> <msg id="NotFound">Cannot find {0} on {1}.</msg> </body> </myRes> [ Example's source code The HTML file with the localization notes is a simple document with the anchor elements corresponding to the identifiers in the referring XML document. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Localization Notes</title> </head> <body lang="en"> <p><a name="NotFound"></a>{0} is a filename<br /> {1} is a directory name</p> </body> </html> [ Example's source code It is also recommended that you define the its:rules its:locNoteRule its:locNoteRule its:locNote The its:locNoteRule locNotePointer locNoteRefPointer its:locNoteRule The its:locNoteRule its:locNote <myDoc> <head> <its:rules xmlns:its="http://www.w3.org/2005/11/its" 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> </myDoc> [ Example's source code Note: its:translate="no" its:rules Storing notes as element content has advantages over storing notes as its:locNote language directionality span-like element Storing notes in an its:locNote Although ITS provides the its:locNote It can be argued that notes, being metadata, have different requirements to the content itself. Schema developers should carefully consider which approach to use. If all notes will always be written by English-speaking content developers, it may be acceptable to use attribute values, but if notes may be written by content developers in Arabic or Hebrew, they are almost certainly going to want to use directional markup and span elements in the notes themselves, so an element-based approach would almost certainly be better. Handling markup not in the ITS namespace If you are working with an existing schema where there is a way to provide notes to the localizers that is not implemented using ITS, you should provide an ITS Rules document its:locNoteRule In this document the comment text <messages> <msg id="ERR_NOFILE"> <text>The file '{0}' could not be found.</text> <comment>The variable {0} is the name of a file.</comment> </msg> </messages> [ Example's source code The its:locNoteRule text comment <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:locNoteRule selector="//msg/text" locNoteType="description" locNotePointer="../comment"/> </its:rules> [ Example's source code Why do this To assist the translator to achieve a correct translation, authors may need to provide information about the text that they have written. For example, the author may want to do the following: Tell the translator how to translate part of the content (e.g. "Leave text in uppercase"). Expand on the meaning or contextual usage of a particular element, such as what a variable refers to or how a string will be used on the UI. 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.) Explain why text is not to be translated, point to text reuse, or describe the use of conditional text. Indicate why a piece of text is emphasized (important, sarcastic, etc.) Resources: Reference links The "Localization Note" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#locNote-datacat More resources Technique index Topic index Best Practice 9: Defining markup for unique identifiers Provide a way for authors to assign unique identifiers to localizable elements. How to do this Make sure that elements with translatable content can be associated with a unique identifier. It is strongly recommended that you define such identifiers as attributes of type ID, following the rules described in xml:id Version 1.0 [xml:id] It is also recommended that you name such attributes xml:id Note: globally unique persistent Why do this In order to most effectively reuse translated text where content is reused (for example across updates) it is necessary to have a unique and persistent identifier associated with the element. This identifier allows the translation tools to correctly track an item from one version or location to the next. After ensuring that this is the same item, the content can be examined for changes, and if no change has taken place the potential for reuse of the previous translation is very high. Change analysis of this kind constitutes an extremely powerful productivity tool for translation when compared to typical source matching techniques (a.k.a. translation memory). These techniques simply look for similar source text in a multilingual database without, most of the time, being able to tell whether the context of its use is the same. Identifiers can also be helpful to track displayed text back to its underlying source. For example, when reviewing a translated user interface, the identifiers can be used as temporary prefixes to the text so that any correction can be efficiently done on the proper strings. Resources: Reference links W3C Recommendation: xml:id http://www.w3.org/TR/2005/REC-xml-id-20050909/ More resources Technique index Topic index Best Practice 10: Identifying terminology-related elements Document in an ITS Rules document what elements are related to terms and term-related information. The ITS Terminology data category its:termRule How to do this Provide an ITS Rules document its:termRule Note: its:termInfoRef In this document, the elements term dt syn <myDoc> <body> <p>A <term def="d001" syn="#alterego">doppelgänger</term> is basically <def xml:id="d001">the counterpart of a person</def>. It is almost the same as an <emph syn="#alterego">alter ego</emph>, but with a more sinister connotation. Sometimes the word <emph syn="#alterego">fetch</emph> is also used.</p> </body> <definitions> <entry xml:id="alterego"> <dt>alter ego</dt> <dd>A second self. Figurative sense: trusted friend.</dd> <origin>Latin, literally: "second I"</origin> </entry> </definitions> </myDoc> [ Example's source code The set of ITS rules below indicates: First termRule term def Second termRule syn syn Third termRule dt dd <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:termRule selector="//term" term="yes" termInfoPointer="id(@def)"/> <its:termRule selector="//*[@syn]" term="yes" termInfoRefPointer="@syn"/> <its:termRule selector="//dt[../dd]" term="yes" termInfoPointer="../dd"/> </its:rules> [ Example's source code Why do this The capability of specifying terms within the source content is important for terminology management and beneficial to translation and localization quality. For example, term identification facilitates the creation of glossaries and allows the validation of terminology usage in the source and translated documents. Term identification is also useful for change management and to ensure source language quality. Terms may require various associated information, such as part of speech, gender, number, term types, definitions, notes on usage, etc. To avoid associated information to be repeated throughout a document, it should be possible for identified terms to link to externalized attribute data, such as glossary documents and terminology database. Resources: Background information "Markup and Terminological Databases" in the Cover Pages http://xml.coverpages.org/terminology.html "Saving Money Through Terminology Management", article. http://www.lisa.org/globalizationinsider/2003/11/the_terms_of_bu.html Reference links The "Terminology" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#terminology More resources Technique index Topic index Best Practice 11: Defining markup for specifying or overriding terminology-related information Provide a way for authors to specify or override terminology-related information using ITS markup, or document equivalent legacy markup in an ITS Rules document. The ITS Terminology data category its:term its:termInfoRef its:termRule How to do this Make sure the its:term its:termInfoRef For examples of how to add attributes in your existing schema see Section 4.2: Example of adding an attribute to an existing schema It is also recommended to define the its:rules its:rules its:termRule Why do this In some cases, the author of a document may need to change the information indicating what is a term or how to point to term information, overriding the general rules for the schema that you have specified when applying Best Practice 10: Identifying terminology-related elements Resources: Background information "Markup and Terminological Databases" in the Cover Pages http://xml.coverpages.org/terminology.html "Saving Money Through Terminology Management", article. http://www.lisa.org/globalizationinsider/2003/11/the_terms_of_bu.html Reference links The "Terminology" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#terminology More resources Technique index Topic index Best Practice 12: Working with multilingual documents Avoid document formats that store multiple localized versions of content within the same document. This best practice refers specifically to situations where copies of the same content are stored in multiple languages in a single document. It is perfectly acceptable to have multilingual text in a document otherwise. How to do this For documents that need to go through some localization tasks, always store the localized version of the text in a separate document. This is an example of bad design. It shows a single document that contains multiple translations of the same content: <messages> <msg xml:id='fileNotFound'> <text xml:lang="en">File not found.</text> <text xml:lang="fr">Fichier non trouvé.</text> </msg> </messages> [ Example's source code Instead, use one document for each language. Here one in English, and the other one in French. Other languages would go in similar separate documents. <messages xml:lang="en"> <msg xml:id='fileNotFound'> <text>File not found.</text> </msg> </messages> [ Example's source code <messages xml:lang="fr"> <msg xml:id='fileNotFound'> <text>Fichier non trouvé.</text> </msg> </messages> [ Example's source code Note: before after Note: XML Localisation Interchange File Format [XLIFF 1.2] Why do this There are two main reasons to avoid sending documents for localization if the source material is located in parallel with the different translations in the same document: It is difficult to manage concurrent translations in all languages. It is very likely that each translation will be done by a different translator, in a different location. To facilitate this, the document will have to be broken down into separate parts and reconstructed later on. This adds processing time, increases cost and provides more opportunities for the introduction of errors. Depending on the point in the document's lifecycle, such a document may already contain translations, some up-to-date and some outdated (because the source material may have changed). In order to identify what parts need to be localized and what parts should be left alone, the document would then also need to contain custom information about localization state, which may or may not be supported by localization tools. Best Practice 13: Naming elements and attributes Use a meaningful and non-dynamic naming scheme for your elements and attributes. How to do this Make sure the names of the elements and attributes of your schema reflect their functions, rather than one possible way of rendering their content. This is an example of bad design. The element b <doc> <p>To run the application, click the <b>Start</b> button.</p> <p><b>Make sure to enter your username</b>, and then press <b>OK</b>.</p> </doc> [ Example's source code Instead, define different elements based on their functions rather than a pre-supposed rendering. <doc> <p>To run the application, click the <ui>Start</ui> button.</p> <p><emph>Make sure to enter your username</emph>, and then press <ui>OK</ui>.</p> </doc> [ Example's source code Also, if possible, avoid element names which do not follow a fixed naming scheme (for example, element names that serve also as identifiers). This is an example of bad design. The names of the elements also serve as text identifiers. <strings> <str1>Input path:</str1> <str2>Help</str2> <str3>OK</str3> <str4>Cancel</str4> </strings> [ Example's source code Instead, use elements names that follow a fixed naming scheme, and use xml:id <strings> <str xml:id="str1">Input path:</str> <str xml:id="str2">Help</str> <str xml:id="str3">OK</str> <str xml:id="str4">Cancel</str> </strings> [ Example's source code Why do this The name of an element should indicate what its function is, not how its content will be presented, because presentation may vary depending on different factors such as language, script, medium, or accessibility. Using documents where elements or attributes do not follow a predictable naming pattern may cause problems when using XSLT-driven processes. It may also be an issue for translation tools. This is especially true if not all parts of the document are to be translated, since it would be more difficult to specify rules to distinguish the translatable nodes from the non-translatable ones. Best Practice 14: Defining a span-like element Provide a way for authors to annotate arbitrary content using its:span or equivalent markup. A span span phrase How to do this Make sure you define a span If your schema does not already provide such an element, you could provide the its:span The definition of the its:span Why do this Some properties of content are applied using attributes. Directionality, terminology, localization notes, translate information, and language identification are examples of such properties. There is a need for a neutral element to delimit the run of text to which such attributes apply, since the appropriate boundaries are sometimes not delimited by other markup that is present, or perhaps those attributes are not permitted on other markup that is present. Resources: Reference links W3C Recommendation: Internationalization Tag Set (ITS) http://www.w3.org/TR/2007/REC-its-20070403/ More resources Technique index Topic index Best Practice 15: Documenting internationalization and localization features of your schema Provide an ITS Rules document containing all the ITS rules needed to interpret legacy markup, and identify translate, terminology and text segmentation information in your format. How to do this Make sure you document the internationalization and localization aspects of your schema by providing a set of relevant ITS rules in a single standalone ITS Rules document. Your ITS Rules document should include the following information, when applicable: The correspondence between any proprietary mechanism you have to specify the language of content and xml:lang Best Practice 1: Defining markup for natural language labelling The correspondence between any proprietary mechanism you have to indicate text directionality and its:dir Best Practice 2: Defining markup to specify text direction What markup has translate rules different from the default expectation that elements are to be translated and attributes are not (see Best Practice 4: Indicating which elements and attributes should be translated The correspondence between any proprietary mechanism you have to override translatability information and its:translate Best Practice 5: Defining markup to override translate information The list of elements that should be treated as "nested" or "within text" from a segmentation viewpoint (see Best Practice 6: Providing information related to text segmentation The correspondence between any proprietary mechanism you have to mark up ruby text and its:ruby Best Practice 7: Defining markup for ruby text What part of your markup holds notes for the localizers (see Best Practice 8: Defining markup for notes to localizers What part of your markup denotes terms and term-related information (see Best Practice 10: Identifying terminology-related elements You can find some examples of ITS Rules documents for existing XML formats in Section 5: ITS Applied to Existing Formats Why do this Although some XML vocabularies are easy to understand or process, it is often helpful or necessary to provide explicit information about a given vocabulary. If such a vocabulary is to be used in a multilingual context, it is of high importance to provide information, such as which elements contain translatable content, because general information on purpose, general structure, and node types very often are not sufficient. In a way, this need for explicit information is related to the general good practice of documenting source code. In XML it should come naturally to use a well-defined, structured format to capture such information. For information related to internationalization and translation, ITS Rules documents are a good choice for the following reasons: They are designed to take into account many important aspects of internationalization and translation. They capture information precisely (for example, selectors identify to which nodes a data category pertains). They can be processed by ITS-aware applications. They can be easily combined with additional structured information (e.g. related to version control, as shown in the example below). An ITS processor should still be able to process a file as an external ITS rules file if the format of the file contains your own customized information in addition to the ITS rules. The following is an example of that. <myFormatInfo xmlns:its="http://www.w3.org/2005/11/its"> <desc>ITS rules used by the Open University</desc> <hostVoc>http://www.example.com/ns/myFormat</hostVoc> <rulesId>98ECED99DF63D511B1250008C784EFB1</rulesId> <rulesVersion>v 1.81 2006/03/28 07:43:21</rulesVersion> <its:rules version="1.0"> <its:translateRule selector="//header" translate="no"/> <its:translateRule selector="//term" translate="no"/> <its:termRule selector="//term" term="yes"/> <its:withinTextRule withinText="yes" selector="//term|//b"/> </its:rules> </myFormatInfo> [ Example's source code Resources: Reference links W3C Recommendation: Internationalization Tag Set (ITS) http://www.w3.org/TR/2007/REC-its-20070403/ More resources Technique index Topic index Authors of XML content should consider the following best practices: Best Practice Summary Specifying the language of content Use xml:lang Specifying text directionality By default the text directionality in an XML document is assumed to be left-to-right. Use its:dir Overriding information about what should be translated Use its:translate Assigning unique identifiers Use unique identifiers in the way provided by your schema on each element that constitutes a segmentation boundary. If possible use globally unique persistent Avoiding CDATA sections Do not put content that will be translated into CDATA sections. Providing notes for localizers Use its:locNote its:locNoteType its:locNoteRef Working with inserted text Use inserted text only when the text is self-contained and does not affect its surrounding context. For example, titles and quotations are inserted text that, usually, would not cause problems. Avoid using inserted text that has any dependence on the context where it is inserted. Identifying terms Use its:term its:termInfoRef Storing markup from another format If possible, use the XML namespace mechanism A number of these practices can be followed only when the XML application has been internationalized properly using the design guidelines in Section 2: When Designing an XML Application Best Practice 16: Specifying the language of content Specify the natural language of your content using xml:lang, or an equivalent mechanism provided by your document format. Your schema should provide the xml:lang Best Practice 1: Defining markup for natural language labelling How to do this Use xml:lang Make sure the values of xml:lang Tags for Identifying Languages [BCP 47] Language tags in HTML and XML xml:lang In this example, the main content of the document is in English, while a short citation in the q xml:lang fr <document xml:lang="en"> <para>The motto of Québec is the short phrase: <q xml:lang="fr">Je me souviens</q>. It is chiseled on the front of the Parliament Building.</para> </document> [ Example's source code If the schema you are using does not provide an xml:lang In this example, the schema for this document type uses a non-standard way to specify language: a code xml:lang stringList code xml:lang lang <stringList> <msg id="connected"> <lang code="cs">Jste připojeni k Internetu.</lang> <lang code="de">Sie sind an das Netz angeschlossen.</lang> <lang code="fr">Vouz êtes connecté à la Toile.</lang> <lang code="it">Sei connesso al Web.</lang> <lang code="ja">インターネットに接続しました。</lang> <lang code="ko">웹에 연결되었습니다.</lang> <lang code="ru">Вы подключены к Интернету.</lang> </msg> </stringList> [ Example's source code Note: Best Practice 12: Working with multilingual documents The developer of the stringList Best Practice 1: Defining markup for natural language labelling its:langRule code lang xml:lang <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:langRule selector="//lang[@code]" langPointer="@code" /> </its:rules> [ Example's source code Note: its:translate its:locNote Best Practice 18: Overriding information about what should be translated Best Practice 21: Providing notes for localizers Why do this Knowing the language of the content is very important in many situations. These include: Selection of a proper font (e.g. for Traditional or Simplified Chinese.) Processing of the text for wrapping and hyphenation. Providing spell-checking or grammar verification of the text. Selecting proper automated selections of text such as quotation marks or other punctuation signs. Using the text with voice browsers. Resources: Background information Internationalization FAQ: xml:lang in XML document schemas. http://www.w3.org/International/questions/qa-when-xmllang Reference links BCP 47 - Tags for Identifying Languages. http://www.rfc-editor.org/rfc/bcp/bcp47.txt Description of the language identification mechanism in the XML specification. http://www.w3.org/TR/REC-xml/#sec-lang-tag Language tags in HTML and XML. http://www.w3.org/International/articles/language-tags/ Tagging text with no language. http://www.w3.org/International/questions/qa-no-language Test data I18N Tests: Automatic font assignment for CJK text (for XHTML). http://www.w3.org/International/tests/sec-cjk-fonts.html More resources Technique index Topic index Best Practice 17: Specifying text directionality Use dedicated markup to specify the directionality of your text content. Your schema should provide its:dir Best Practice 2: Defining markup to specify text direction How to do this By default the text directionality in an XML document is assumed to be left-to-right. Use its:dir You can get additional guidance on when and how to use directional markup in Internationalization Best Practices: Handling Right-to-left Scripts in XHTML and HTML Content What you need to know about the bidi algorithm and inline markup In this example, the attribute its:dir <text xmlns:its="http://www.w3.org/2005/11/its" xml:lang its:version <body> <par> <quote xml:lang its:dir פעילות הבינאום, W3C </quote <quote> </quote </par </body </text [ Example's source code Without the markup, the Hebrew title will display incorrectly. The text 'W3C' and the comma will be to the right of the quoted Hebrew text, rather than to its left. The markup provides the contextual information that tells the user agent that the comma and 'W3C' text are part of a right-to-left flow of text. Note: Problems with bidirectional source text [Bidi in X/HTML] Note: Unicode Bidi Embedding Controls Bidi formatting codes vs. markup for bidi support You also need to use dedicated markup to apply directional information, rather than just applying CSS direction properties to ordinary elements. See CSS vs. markup for bidi support Why do this User agents should use the Unicode Bidirectional (bidi) Algorithm and its knowledge of the directional properties of characters to decide whether a sequence of characters should flow to the left or to the right. The bidi algorithm can also handle simple cases where right-to-left and left-to-right text are mixed. However, situations commonly arise where higher level contextual information is needed to achieve the desired layout of bidirectional text. This contextual information can be provided by markup in XML. Such markup also affects page layout behavior. For example, in a right-to-left context, table columns are ordered right-to-left, list bullets appear to the right of text, the page is right-aligned, and so forth. Note: There is not necessarily a one-to-one match between a given language and what directionality to use. For example, Azerbaijani can be written using both right-to-left and left-to-right scripts, and the language code az The values of inline directional markup are not necessarily aligned with the values of markup about the language. For example, a part of a document might be declared as having right-to-left directionality, but there might be only a general language declaration for a left-to-right script language available, like fr Markup used to indicate directionality has values that indicate that the normal directionality should be overridden; it is not possible to indicate that using language related values. Resources: Background information Internationalization FAQ: What you need to know about the bidi algorithm and inline markup http://www.w3.org/International/articles/inline-bidi-markup/ Unicode Technical Report #20: Unicode in XML and other Markup Languages http://www.w3.org/TR/2007/NOTE-unicode-xml-20070516/ Reference links The "Directionality" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#directionality More resources Technique index Topic index Best Practice 18: Overriding information about what should be translated Use available markup to specify any content where the choice to translate or not is different from the default for your schema. Your schema should provide its:translate Best Practice 5: Defining markup to override translate information The ITS default is that element content should be translated and attribute content should not. Developers of your schema should also have documented any schema-specific defaults How to do this Use its:translate In the following document, although the content of the par par its:translate par Note that the author does not need to specify that the head myDoc ITS Rules document myDoc <myDoc xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"> <head> <lastRev>2007-10-23 041254Z</lastRev> <docID>1A454AE4-7EB8-4ed2-A58E-1EC7F75BB0D5</docID> </head> <par>To apply these terms to you library, attach the following notice. It is safest to attach it to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.</par> <par>The notice should read (preferably in English):</par> <par its:translate="no">This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This software is distributed as open source under LGPL.</par> </myDoc> [ Example's source code This is the ITS Rules document created by the developer of the myDoc Best Practice 4: Indicating which elements and attributes should be translated <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:translateRule selector="/myDoc/head" translate="no"/> <its:translateRule selector="//img/@alt" translate="yes"/> </its:rules> [ Example's source code This is what the rules mean: First translateRule head Second translateRule alt img To override translate information for attributes, you have to use an its:translateRule This document is of the same type as the one in Example 21 alt alt its:translateRule <myDoc xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"> <head> <lastRev>2007-11-12 234503Z</lastRev> <docID>D1EA7453-DC53-488a-B950-137BE0EF5253</docID> <its:rules> <its:translateRule selector="//img[@role='ui']/@alt" translate="no"/> </its:rules> </head> <par>Once you have selected your options, click the <img xml:lang="en-us" src="runBtn.png" role="ui" alt="Run"/> button to start the process.</par> </myDoc> [ Example's source code The its:translateRule Note: its:translate Authors may decide what how its:translate This is an example of bad design. In this document its:translate not <book xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"> <body> <p>Everything started when <span its:translate="no">Zebulon</span> discovered that he had a <span its:translate="no">doppelgänger</span> who was a serious baseball <span its:translate="no">aficionado</span>.</p> </body> </book> [ Example's source code It may, however, be useful to the translator to mark up loan-words or any special words in this example as terms Best Practice 23: Identifying terms Why do this Although the set of ITS rules provided with the schema should specify any exceptions to the default ITS translation rules for a given schema (see Best Practice 4: Indicating which elements and attributes should be translated Best Practice 19: Assigning unique identifiers Assign a unique identifier to elements that correspond to segmentation boundaries. Your schema should provide xml:id Best Practice 9: Defining markup for unique identifiers Segmentation refers to how text is broken down, from a linguistic viewpoint, into units that can be stored separately and handled by processes such as translation. The schema author ought to create a list of these elements where they differ from the ITS defaults (see Best Practice 6: Providing information related to text segmentation How to do this Use unique identifiers in the way provided by your schema on each element that constitutes a segmentation boundary. Note: If possible use globally unique persistent Why do this Providing unique identifiers can be very useful for change analysis, text tracking, and various other tasks often utilized during the authoring and the localization of documents. This is explained in more detail in Best Practice 9: Defining markup for unique identifiers Resources: Background information "Give unique identifiers to elements in XML documents", note. http://www.ibm.com/developerworks/xml/standards/x-xmlidspec.html Reference links W3C Recommendation: xml:id http://www.w3.org/TR/2005/REC-xml-id-20050909/ More resources Technique index Topic index Best Practice 20: Avoiding CDATA sections Avoid using CDATA sections for content that will be translated. CDATA sections are often used to place programming code or other special vocabularies in XML with minimal effort. There are often better ways of including such content. How to do this Do not put content that will be translated into CDATA sections. This is an example of bad design. In this document, part of the content is in a CDATA section. It is no longer possible to mark up that content for language changes, terms, text direction, translate information, or any of the other things that may be needed to facilitate localization. <myData> <item course="12" page="2"> <title>Accessing the R&D facilities</title> <body><![CDATA[The R&D facilities are located in the South wing of Building 12-W, in the East quarter of the section Q. IMPORTANT ==> These facilities are accessible only to personal with Class Omega-45Q1 clearance.]]></body> </item> </myData> [ Example's source code Instead, use normal XML for your content. This allows you to tag the content as needed. For instance, here the author has added some terminology markup. <myData xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"> <item course="12" page="2"> <title>Accessing the R&D facilities</title> <body>The R&D facilities are located in the South wing of Building 12-W, in the East quarter of the section Q. IMPORTANT ==> These facilities are accessible only to personal with <span its:term="yes">Class Omega-45-Q1</span> clearance.</body> </item> </myData> [ Example's source code If the CDATA section encloses a large, self-contained block of data, such as a script or an XML example, you may be able to replace the section by some inclusion mechanism such as XInclude XLink In SVG you can place a script directly into an SVG document, in which case you usually use CDATA sections to avoid having to escape characters in the script's code. <?xml version="1.0" encoding="utf-8"?> <svg width="6cm" height="5cm" viewBox="0 0 600 500" xmlns="http://www.w3.org/2000/svg" version="1.1"> <!-- Script is inlined and enclosed in CDATA section --> <script type="text/ecmascript"> <![CDATA[ function circle_click(evt) { var circle = evt.target; var currentRadius = circle.getAttribute("r"); if (currentRadius < 100) circle.setAttribute("r", currentRadius*2); else circle.setAttribute("r", currentRadius*0.5); } ]]> </script> <rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/> <circle onclick="circle_click(evt)" cx="300" cy="225" r="10" fill="red"/> <text x="300" y="480" font-family="Verdana" font-size="35" text-anchor="middle"> Click on circle to change its size </text> </svg> [ Example's source code Instead, you could use XLink to store the script in a separate file and reference it from the SVG document. <?xml version="1.0" encoding="utf-8"?> <svg width="6cm" height="5cm" viewBox="0 0 600 500" xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink"> <!-- Script is included from external file --> <script type="text/ecmascript" xlink:href="animate.js"/> <rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/> <circle onclick="circle_click(evt)" cx="300" cy="225" r="10" fill="red"/> <text x="300" y="480" font-family="Verdana" font-size="35" text-anchor="middle"> Click on circle to change its size </text> </svg> [ Example's source code It is quite common to use CDATA sections to put examples of source code into XML documents. The following example shows how to do this using DocBook. <?xml version="1.0" encoding="utf-8"?> <example xmlns="http://docbook.org/ns/docbook"> <title>Skeleton of XHTML page</title> <programlisting><![CDATA[<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <title>… page title goes here …</title> </head> <body> … page content goes here … </body> </html>]]></programlisting> </example> [ Example's source code Instead, you could use XInclude to store the example code in a separate file and include it during at processing time. Note that you have to use parse="text" <?xml version="1.0" encoding="utf-8"?> <example xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Skeleton of XHTML page</title> <programlisting><xi:include href="EX-xhtml-skeleton.xhtml" parse="text" encoding="utf-8"/></programlisting> </example> [ Example's source code If you must use CDATA sections: Document the type of content (for example with an attribute set to the appropriate MIME-type). This may help tools to use an appropriate parser to process the content. Aim to produce well-formed content. This will allow parsers to process the content more easily. Note: Best Practice 24: Storing markup from another format Note: xml:space preserve Why do this The use of CDATA sections prevents the insertion of markup for internationalization or localization purposes. For example, tags to denote change of directionality, or language, or to add localization notes, cannot be used with the content inside CDATA sections. Numeric character references and entity references are not supported in CDATA sections either. This could lead to a possible loss of data if the document is converted from one encoding to another, or when translating. Mixing content in CDATA sections and content not in CDATA sections in the same document causes more work when doing some tasks with non-XML-aware tools. For example, when searching for the text "R&D" the user has to search both for R&D R&D Best Practice 21: Providing notes for localizers Use dedicated markup to provide notes where you can communicate useful information for the localizer Your schema should provide its:locNote its:locNoteType its:locNoteRef Best Practice 8: Defining markup for notes to localizers How to do this Use its:locNote its:locNoteType its:locNoteRef This is especially important for content with inserted text In this document two ITS local attributes are used to annotate an XSLT template: its:locNoteRef its:locNote <xsl:value-of select="PNum"/> Note: <?xml version="1.0"?> <xsl:stylesheet version="1.0" xmlns="http://www.w3.org/1999/xhtml" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"> <xsl:template match="/data"> <xsl:variable name="Lang" select="Lang"/> <xsl:variable name="EMail" select="EMail"/> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{$Lang}" lang="{$Lang}"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> <title>Login</title> </head> <body> <p>Login Into Queztal-Systems</p> <form method="POST"> <table border="0" id="table2"> <tr><td>First, place your pass card in front of the reader to scan your <xsl:text its:locNoteRef="http://en.wikipedia.org/wiki/RFID">RFID</xsl:text>. When the light turns green, enter your password in the box below, and click Submit.</td></tr> <tr><td><input type="password" name="pword" size="25"/></td></tr> </table> <p><input type="submit" value="Submit" name="go"/></p> </form> <p>If you have difficulties login in, please call <xsl:value-of select="PNum" its:locNote="Toll-free phone number"/>, or send an email to <a href="mailto:{$EMail}"><xsl:value-of select="EMail"/></a>.</p> </body> </html> </xsl:template> </xsl:stylesheet> [ Example's source code Why do this There are many reasons to provide information to localizers. You may want to: Expand on the meaning or contextual usage of a particular element, such as what a variable refers to or how a string will be used in the user interface. Clarify ambiguity and show relationships between items sufficiently to allow correct translation. For example, 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. Explain why text is not translated, point to text reuse, or describe the use of conditional text. Indicate why a piece of text is emphasized (important, sarcastic, etc.) Using XML comments for doing this may not be enough as they may get stripped out or ignored during the localization process. Best Practice 22: Working with inserted text Make sure that any piece of inserted text is grammatically independent of its surrounding context. Inserted text refers to any text that is marked by a placeholder in the source XML document and automatically inserted within text content when the document is processed. Types of inserted text include: Boilerplate text reused in different contexts. Various parts of a sentence composed by bringing together separate pieces of text. Variable placeholders that are replaced by their values when the document is processed. The implementation of such text can be done in different ways in XML. Some examples are: Using entity references. Using XSLT processing. Using XInclude Using XLink Using a custom mechanism specific to a given format (e.g. the conref [DITA 1.0] How to do this Use inserted text only when the text is self-contained and does not affect its surrounding context. For example, titles and quotations are inserted text that, usually, would not cause problems. Avoid using inserted text that has any effect or dependence on the context where it is inserted. For additional background information about issues and approaches related to text insertion and re-use of text see the articles Working with Composite Messages Re-using Strings in Scripted Content If you do insert text, use its:locNote its:termInfoRef Best Practice 21: Providing notes for localizers Best Practice 23: Identifying terms In this example, in the first message, the element var its:locNote <strings xmlns:its="http://www.w3.org/2005/11/its" xml:lang="en" its:version="1.0"> <msg id="pmAdded">The printer <var arg="0" its:locNote="Printer name"/> has been added to the list.</msg> <msg id="fmAdded">The file <var arg="0" its:locNote="Filename"/> has been added to the list.</msg> </strings> [ Example's source code This is a French translation of the document shown above. The context provided allowed to disambiguate the variable and to get a more accurate translation. <strings xmlns:its="http://www.w3.org/2005/11/its" xml:lang="fr" its:version="1.0"> <msg id="pmAdded">L'imprimante <var arg="0" its:locNote="Printer name"/> a été ajoutée à la liste.</msg> <msg id="fmAdded"><var arg="0" its:locNote="Filename"/> a été ajouté à la liste.</msg> </strings> [ Example's source code Why do this If not used properly, inserted text can cause important (and sometimes unresolvable) problems during localization. Consider the following: conref This is an example of bad design. In this example, the author, working with the DITA format [DITA 1.0] conref t123 termbase.xml hydraulic lift <p>Using a <term conref="termbase.xml#t123"/>, raise the vehicle from the ground.</p> At a first glance the example above seems to work fine in English. However, such a construction has several problems: You should not separate the article from the noun. If "hydraulic lift" is independently replaced in the future by some other term, you may need to change the article to ' an The article/noun separation also causes trouble for the translators. Without any easy way to see the actual term when translating the paragraph, they may not be able to decide the gender or number of the article. If it is used at the beginning of a different sentence, the term would need to be capitalized. The term is singular in the termbase, but it may need to be plural somewhere else in the document. In inflected languages the form required in the text may be different from the form stored in the termbase. For example, in Polish the term would be stored in its nominative form ( " dźwignia hydrauliczna Używając dźwignię hydrauliczną podnieś pojazd z ziemi. Resources: Background information Internationalization article: Working with Composite Messages. http://www.w3.org/International/articles/composite-messages/ Internationalization article: Re-using Strings in Scripted Content http://www.w3.org/International/articles/text-reuse/ More resources Technique index Topic index Best Practice 23: Identifying terms Use dedicated markup to identify any terminology-related content. What constitutes a term depends on many factors specific to each organization and project. Terms may include for example names of features, programs, services, and so forth. They also may include words or expressions that are specific to the domain to which the content pertains, such as technical terms, or legal terms, and they may include terms that simply occur often and should be translated consistently. How to do this Use its:term its:termInfoRef Your schema should provide its:term its:termInfoRef Best Practice 11: Defining markup for specifying or overriding terminology-related information You should also override default terminology rules as needed. In this document, terms are normally denoted with a term Best Practice 10: Identifying terminology-related elements term However, in this specific document, the author wants to indicate the following: The content of any ui The text Vector Files In the first case, the author uses a its:termRule ui ui In the second case, because the schema does not allow the element term title span its:term its:termInfoRef Vector Files <myManual xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"> <head> <its:rules> <its:termRule selector="//ui" term="yes"/> </its:rules> <title>Generating <span its:term="yes" its:termInfoRef="#vFile">Vector Files</span></title> </head> <body> <par>Select the command <ui>Build Output Files</ui> from the <ui>Tasks</ui> menu to generate the final <term ref="vFile">vector files</term>.</par> </body> <extra> <terms> <termDef xml:id="vFile">A <emph>vector file</emph> is a binary document that contains the complete set of vectors needed to draw the background layer of a map.</termDef> </terms> </extra> </myManual> [ Example's source code This ITS Rules document is the one created by the developer of the myManual Best Practice 10: Identifying terminology-related elements termRule term ref term <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <its:termRule selector="//term" term="yes" termInfoRef="id(@ref)"/> </its:rules> [ Example's source code Why do this If you do not indicate what words are terms of interest in the content, the translators will not know that these terms need to be translated consistently. Often, multiple translators are working on different files in a given project, and the way they choose to translate specific words can be inconsistent with the way that other translators have translated them. If important terms are marked in the content, they can extract these terms from the content before the content is translated, and pre-translate them in the form of a shared electronic dictionary. This ensures consistency of translation of important terms. While markup denoting terms for a given schema level should be specified in a set of ITS rules provided with the schema (See Best Practice 10: Identifying terminology-related elements Resources: Reference links The "Terminology" data category in ITS. http://www.w3.org/TR/2007/REC-its-20070403/#terminology More resources Technique index Topic index Best Practice 24: Storing markup from another format Avoid escaping markup to enable storage of markup from another format. How to do this If possible, use the XML namespace mechanism In this document, the elements top body <pages> <row> <key>ENConvClasses</key> <top><span class="h1">Elibur Library</span> - Conversation Groups</top> <body><![CDATA[<p>These small discussion groups meet <b>weekly</b> and are for people learning English. Each group is led by a volunteer who is a native speaker of American English. Groups converse about books, articles, and other materials.</p> <p>Space is limited. Ask for availability to <a href="mailto:[email protected]"> [email protected]</a>.</p>]]></body> </row> </pages> [ Example's source code Instead, use the XML namespace mechanism. Here the content of top body <pages xmlns:h="http://www.w3.org/1999/xhtml"> <row> <key>ENConvClasses</key> <top><h:span class="h1">Elibur Library</h:span> - Conversation Groups</top> <body><h:p>These small discussion groups meet <h:b>weekly</h:b> and are for people learning English. Each group is led by a volunteer who is a native speaker of American English. Groups converse about books, articles, and other materials.</h:p> <h:p>Space is limited. Ask for availability to <h:a href="mailto:[email protected]">[email protected]</h:a>.</h:p></body> </row> </pages> [ Example's source code Another alternative to using markup as text is to store it externally and include it into the document using a mechanism such as XInclude XLink If you must include markup as text content: Make sure to document the type of content, for example with an attribute set to the appropriate MIME-type. This may help tools to use a more appropriate parser to process the given content. Aim at having the content well-formed. This will allow parsers to process it more easily. Why do this Some XML documents are used to store different types of data for purposes such as exchange or export. In some cases such data is itself XML data. For example, some XHTML content stored in a database can be exported to an XML container file for localization and re-imported back into the database. Note: Storing such XML data inside XML elements as text content (i.e. with its markup tags escaped), has several drawbacks: Any handling of such content is made difficult by the impossibility to separate text from markup without extra processing. Often, such content is put in CDATA sections, which has its own set of issues. See Best Practice 20: Avoiding CDATA sections The escaped markup cannot be validated. If there is a process turning markup into escaping, there is the danger of double escaping. This section provides a set of generic techniques that are applicable to various guidelines; for example, how to add ITS attributes to different types of schemas, or how to optimize XPath expressions for the ITS selector Whether they are external or embedded, there are a few things you should take into consideration when writing ITS rules. Try to keep the number of nodes to be overridden to a minimum. This improves performance. For example, if most of a document should not be translated, it is better to set the root element to be non-translatable than to set all elements. The inheritance mechanism will have the same effect for a much lower computing cost. Because a rule has precedence over the ones before, you should start with the most general rules first and progressively override them as needed. Some rules may be more complex if they need to take into account all the aspects of inheritance. ITS 1.0 defines the precedence of ITS information ITS Translate data category ITS local attributes its:translate Next are global rules its:translateRule ITS Translate data category its:rules its:rules its:rules xlink:href its:rules Inherited ITS information ITS information which originates in data category specific defaults is the one with the lowest precedence. For example, the default for the ITS Translate data category The following example shows the usage of local and global ITS markup and how the precedence described above comes into play. In this document, all child elements within the <text> its:translateRule its:translateRule <p> Another exception to the first its:translateRule its:translate <notes> its:translate its:translateRule <notes> Finally, the content of the <documentation> <head> ITS Translate data category <doc xmlns:its="http://www.w3.org/2005/11/its"> <head> <documentation>Some translatable text.</documentation> <its:rules version="1.0"> <its:translateRule selector="//text" translate="no"/> <its:translateRule selector="//p" translate="yes"/> </its:rules> </head> <text> <data>Some data with <code>coded parts</code> (<notes its:translate="yes"> and translatable text</notes>).</data> <p>Some text with <b>bolded words</b>.</p> </text> </doc> [ Example's source code When writing rules for documents that use XML namespaces you must make sure that you declare the namespaces, and use the relevant prefixes in the different XPath expressions. The first document uses several different XML vocabularies: The host format is not associated with any namespace. Its elements have no prefix. The "inventory-book" vocabulary is associated with the namespace http://www.example.com/inventory-book bk The XHTML vocabulary is associated with the namespace http://www.w3.org/1999/xhtml h The XLink vocabulary is associated with the namespace http://www.w3.org/1999/xlink xlink The ITS vocabulary is associated with the namespace http://www.w3.org/2005/11/its its <inventory xmlns:bk="http://www.example.com/inventory-book" xmlns:h="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:its="http://www.w3.org/2005/11/its"> <header> <identity>3E039D7D-B416-47e8-83B3-3F4DF9EDDB87</identity> <lastUpdate>2007-11-12</lastUpdate> <desc>Inventory made by Joan, for shelves H to K only.</desc> <its:rules version="1.0" xlink:href="EX-namespaces-2.xml" xlink:type="simple"/> </header> <list> <bk:book xml:id="item00A83"> <bk:isbn>0312875819</bk:isbn> <bk:quantity>2</bk:quantity> <bk:type>HIST</bk:type> <bk:author>Bradshaw, Gillian</bk:author> <bk:pub>Forge Books; New Ed edition (June 2, 2001)</bk:pub> <bk:title>The Sand-Reckoner</bk:title> <bk:desc> <h:p>Building on a few antique facts, Bradshaw ably recreates the extraordinary life of Archimedes, the great mathematician and engineer who lived in Syracuse from 287 to 212 B.C. After a few years studying in Alexandria, Archimedes returns home where his father is dying and his city at war with the Romans. <h:img src="0312875819large.png" alt="The Sand-Reckoner (by Gillian Bradshaw)"/> </h:p> </bk:desc> </bk:book> </list> </inventory> [ Example's source code The XLink and ITS namespaces are just used for associating this document with the external ITS rules file shown below. The ITS Rules document contains several rules that determine what parts of the inventory document should be translated. The rules use XPath expressions where the elements are prefixed. These prefixes are associated with the namespaces used in the inventory. Here is a description of each its:translateRule The first indicates that the inventory inventory The second indicates that the desc The third indicates that the title http://www.example.com/inventory-book The fourth indicates that the desc http://www.example.com/inventory-book The last indicates that the alt img <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0" xmlns:book="http://www.example.com/inventory-book" xmlns:html="http://www.w3.org/1999/xhtml"> <its:translateRule selector="//inventory" translate="no"/> <its:translateRule selector="//desc" translate="yes"/> <its:translateRule selector="//book:title" translate="yes"/> <its:translateRule selector="//book:desc" translate="yes"/> <its:translateRule selector="//html:img/@alt" translate="yes"/> </its:rules> [ Example's source code ITS uses XPath expressions in several contexts to identify nodes. The most prominent contexts are selectors, and pointer attributes like those shown in the following rules: <its:translateRule selector="//term" translate="no"/> or <its:locNoteRule locNoteType="description" selector="//msg/data" locNotePointer="../notes"/> When writing ITS-related XPath expressions like the ones above, the following should be considered: ITS XPath expressions pertain to XPath 1.0 or its successor The values of ITS selector attributes are XPath absolute location paths The values of ITS pointer attributes are XPath relative location paths. The ITS pointer attributes are: locNotePointer locNoteRefPointer its:termInfoPointer its:termInfoRefPointer its:rubyPointer its:rtPointer its:rpPointer its:rbcPointer its:rtcPointer its:rbspanPointer its:langPointer In environments where XSLT is used to process ITS-related XPath expressions, it is important to know about the subset of XPath which is termed ' XSLT patterns Global Approach match template In addition to this general advice, you should take into account best practices related to writing XPath expressions (see for example the XPath tutorial This example shows how to add an attribute (here xml:lang para Note that this example only shows a few ways of adding attributes. There are many others, depending on the schema language and the modularization techniques used in the existing schema. xml:lang To include the xml:lang xs:import xml:lang <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <!-- Import for xml:lang and xml:space --> <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"/> ... Once the xml.xsd schema is imported, you can use the reference to xml:lang xml:lang ... <xs:element name="para"> <xs:complexType> <xs:sequence maxOccurs="unbounded"> ... </xs:sequence> <xs:attribute ref="xml:lang" use="optional"/> </xs:complexType> </xs:element> ... xml:lang Declare xml:lang xml:lang xml:lang language xml:lang <element name="para" xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> <attribute name="xml:lang"> <choice> <data type="language"/> <value></value> </choice> </attribute> ... </element> xml:lang Add the xml:lang For example, to add xml:lang para xml:lang <!ELEMENT para (#PCDATA)> <!ATTLIST para xml:lang CDATA #IMPLIED> This section presents several examples of how ITS can be used to enhance the internationalization readiness of some well-known XML document types. These examples are only illustrative and may have to be adapted to fit the needs of each specific user. Two topics are covered for each format: How should ITS be integrated in specific markup schemas? For example, for XHTML it promotes the interoperability of ITS implementations if you specify that the ITS rules head How should ITS data categories be associated with existing markup declarations in a schema that have identical or overlapping purposes? For example, DITA [DITA 1.0] selection The following XML vocabularies are discussed: Section 5.1: ITS and XHTML 1.0 Section 5.2: ITS and TEI Section 5.3: ITS and XML Spec Section 5.4: ITS and DITA Section 5.5: ITS and GladeXML Section 5.6: ITS and DocBook XHTML [XHTML 1.0] In XHTML 1.0, the XHTML namespace may be used with other XML namespaces as per Namespaces in XML [XML Names] no longer strictly conformant Here is an example of a document containing ITS rules which is a non-conformant <html xmlns="http://www.w3.org/1999/xhtml" xmlns:its="http://www.w3.org/2005/11/its" lang="en" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="keywords" content="ITS example, XHTML translation" /> <its:rules version="1.0" xmlns:h="http://www.w3.org/1999/xhtml"> <its:translateRule selector="//h:meta[@name='keywords']/@content" translate="yes" /> <its:termRule selector="//h:span[@class='term']" term="yes" /> </its:rules> <title>ITS Working Group</title> </head> <body> <h1>Test of ITS on <span class="term">XHTML</span></h1> <p>Some text to translate.</p> <p its:translate="no">Some text not to translate.</p> </body> </html> [ Example's source code There are three ways to use ITS with XHTML and keep the XHTML document conformant: Use XHTML Modularization [XHTMLMod1.1] Section 5.1.2: Using XHTML Modularization 1.1 for the Definition of ITS Use external ITS global rules, as shown in the following example. Even local information within the document that would be handled by ITS attributes can be set indirectly. These rules illustrate some of the ITS data categories you can associate with specific XHTML markup. The first its:translateRule content meta name its:translateRule p class="notrans" its:termRule span class="term" <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0" xmlns:h="http://www.w3.org/1999/xhtml"> <its:translateRule selector="//h:meta[@name='keywords']/@content" translate="yes" /> <its:translateRule selector="//h:p[@class='notrans']" translate="no" /> <its:termRule selector="//h:span[@class='term']" term="yes" /> </its:rules> [ Example's source code The corresponding document: <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="keywords" content="ITS example, XHTML translation" /> <title>ITS Working Group</title> </head> <body> <h1>Test of ITS on <span class="term">XHTML</span></h1> <p>Some text to translate.</p> <p class="notrans">Some text not to translate.</p> </body> </html> [ Example's source code Use NVDL. See Section 5.1.3: Using NVDL to integrate ITS into XHTML This section describes how to use XHTML Modularization 1.1 [XHTMLMod1.1] The following is the abstract definition of the elements for global ITS markup [XHTMLMod1.1] [XHTMLMod1.1] Note that this definition does not contain the ruby dir its:rules Section 5.1.4: Associating existing XHTML markup with ITS Elements Attributes Minimal Content Model rules version (CDATA), xlink:href (URI), xlink:type ("simple") ( translateRule locNoteRule termRule dirRule rubyRule langRule withinTextRule translateRule Selector EMPTY locNoteRule Selector locNote? locNote translate ("yes"|"no"), locNote (CDATA), locNoteType ( "alert" | "description"), locNoteRef (URI), termInfoRef ( URI ), term ( "yes" | "no" ), dir ( "ltr" | "rtl" | "lro" | "rlo" ) (PCDATA | ruby termRule Selector EMPTY dirRule Selector EMPTY rubyRule Selector rubyText rubyText translate ("yes"|"no"), locNote (CDATA), locNoteType ("alert"|"description"), locNoteRef (URI), term ("yes" | "no"), termInfoRef (CDATA), dir ("ltr" | "rtl" | "lro" | "rlo" ), rbspan (CDATA) PCDATA langRule Selector EMPTY withinTextRule Selector EMPTY The following are the abstract definitions of two attribute groups: the selector global rules ITS attributes to be used locally Collection Attributes in Collection Selector selector (CDATA) ITSLocal translate ("yes"|"no"), locNote (CDATA), locNoteType ("alert"|"description"), locNoteRef (URI), termInfoRef (URI), term ("yes" | "no") The following schema contains the implementation of the abstract markup module in XML Schema. <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.w3.org/2005/11/its" xmlns:its="http://www.w3.org/2005/11/its" xmlns:h="http://www.w3.org/1999/xhtml" elementFormDefault="qualified" xmlns:xlink="http://www.w3.org/1999/xlink"> <xs:import namespace="http://www.w3.org/1999/xlink" schemaLocation="xlink.xsd"/> <xs:import namespace="http://www.w3.org/1999/xhtml" schemaLocation="xhtml-schemas/xhtml-ruby-1.xsd"/> <xs:simpleType name="translate.type"> <xs:restriction base="xs:string"> <xs:enumeration value="yes"/> <xs:enumeration value="no"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="term.type"> <xs:restriction base="xs:string"> <xs:enumeration value="yes"/> <xs:enumeration value="no"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="locNoteType.type"> <xs:restriction base="xs:string"> <xs:enumeration value="alert"/> <xs:enumeration value="description"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="dir.type"> <xs:restriction base="xs:string"> <xs:enumeration value="ltr"/> <xs:enumeration value="ltr"/> <xs:enumeration value="lro"/> <xs:enumeration value="rlo"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="withinText.type"> <xs:restriction base="xs:string"> <xs:enumeration value="yes"/> <xs:enumeration value="no"/> <xs:enumeration value="nested"/> </xs:restriction> </xs:simpleType> <xs:attributeGroup name="its.Selector.attlist"> <xs:attribute name="selector" type="xs:string" use="required"/> </xs:attributeGroup> <xs:attributeGroup name="its.ITSLocal.attlist"> <xs:attribute name="translate" form="qualified" use="optional" type="its:translate.type"/> <xs:attribute name="locNote" type="xs:string" form="qualified" use="optional"/> <xs:attribute name="locNoteType" form="qualified" use="optional" type="its:locNoteType.type"/> <xs:attribute name="locNoteRef" type="xs:anyURI" form="qualified" use="optional"/> <xs:attribute name="termInfoRef" type="xs:string" form="qualified" use="optional"/> <xs:attribute name="term" type="its:term.type" form="qualified" use="optional"/> </xs:attributeGroup> <xs:element name="rules" type="its:rules.type"/> <xs:complexType name="rules.type" mixed="false"> <xs:choice minOccurs="0" maxOccurs="unbounded"> <xs:element ref="its:translateRule"/> <xs:element ref="its:locNoteRule"/> <xs:element ref="its:termRule"/> <xs:element ref="its:dirRule"/> <xs:element ref="its:rubyRule"/> <xs:element ref="its:langRule"/> <xs:element ref="its:withinTextRule"/> </xs:choice> <xs:attributeGroup ref="its:rules.attlist"/> </xs:complexType> <xs:attributeGroup name="rules.attlist"> <xs:attribute name="version" use="required" type="xs:string"/> <xs:attribute ref="xlink:href" use="optional"/> <xs:attribute ref="xlink:type" use="optional"/> </xs:attributeGroup> <xs:element name="translateRule" type="its:translateRule.type"/> <xs:complexType name="translateRule.type"> <xs:attributeGroup ref="its:its.Selector.attlist"/> <xs:attribute name="translate" use="required" type="its:translate.type"/> </xs:complexType> <xs:element name="locNoteRule" type="its:locNoteRule.type"/> <xs:complexType name="locNoteRule.type"> <xs:sequence minOccurs="0" maxOccurs="1"> <xs:element ref="its:locNote"/> </xs:sequence> <xs:attributeGroup ref="its:its.Selector.attlist"/> <xs:attribute name="locNotePointer" type="xs:string" use="optional"/> <xs:attribute name="locNoteType" use="required" type="its:locNoteType.type"/> <xs:attribute name="locNoteRef" type="xs:anyURI" use="optional"/> <xs:attribute name="locNoteRefPointer" type="xs:string" use="optional"/> </xs:complexType> <xs:element name="locNote" type="its:locNote.type"/> <xs:complexType name="locNote.type" mixed="true"> <xs:attribute name="translate" use="optional" type="its:translate.type"/> <xs:attribute name="locNote" type="xs:string" use="optional"/> <xs:attribute name="locNoteType" use="optional" type="its:locNoteType.type"/> <xs:attribute name="locNoteRef" type="xs:anyURI" use="optional"/> <xs:attribute name="termInfoRef" type="xs:anyURI" use="optional"/> <xs:attribute name="term" use="optional" type="its:term.type"/> <xs:attribute name="dir" use="optional" type="its:dir.type"/> </xs:complexType> <xs:element name="termRule"/> <xs:complexType name="termRule.type"> <xs:attributeGroup ref="its:its.Selector.attlist"/> <xs:attribute name="term" type="its:term.type" use="required"/> <xs:attribute name="termInfoRef" type="xs:anyURI" use="optional"/> <xs:attribute name="termInfoRefPointer" type="xs:string" use="optional"/> <xs:attribute name="termInfoPointer" type="xs:string" use="optional"/> </xs:complexType> <xs:element name="dirRule" type="its:dirRule.type"/> <xs:complexType name="dirRule.type"> <xs:attributeGroup ref="its:its.Selector.attlist"/> <xs:attribute name="dir" type="its:dir.type" use="required"/> </xs:complexType> <xs:element name="rubyRule"/> <xs:complexType name="rubyRule.type"> <xs:sequence> <xs:element ref="its:rubyText"/> </xs:sequence> <xs:attributeGroup ref="its:its.Selector.attlist"/> <xs:attribute name="rubyPointer" type="xs:string" use="optional"/> <xs:attribute name="rtPointer" type="xs:string" use="optional"/> <xs:attribute name="rpPointer" type="xs:string" use="optional"/> <xs:attribute name="rbcPointer" type="xs:string" use="optional"/> <xs:attribute name="rtcPointer" type="xs:string" use="optional"/> <xs:attribute name="rbspanPointer" type="xs:string" use="optional"/> </xs:complexType> <xs:element name="rubyText" type="its:rubyText.type"/> <xs:complexType name="rubyText.type" mixed="true"> <xs:attribute name="translate" type="its:translate.type" use="optional"/> <xs:attribute name="locNote" type="xs:string" use="optional"/> <xs:attribute name="locNoteType" type="its:locNoteType.type" use="optional"/> <xs:attribute name="locNoteRef" type="xs:anyURI" use="optional"/> <xs:attribute name="term" type="its:term.type" use="optional"/> <xs:attribute name="termInfoRef" type="xs:string" use="optional"/> <xs:attribute name="dir" type="its:dir.type" use="optional"/> <xs:attribute name="rbspan" type="xs:string" use="optional"/> </xs:complexType> <xs:element name="langRule"/> <xs:complexType name="langRule.type"> <xs:attributeGroup ref="its:its.Selector.attlist"/> <xs:attribute name="langPointer" type="xs:string" use="required"/> </xs:complexType> <xs:element name="withinTextRule"/> <xs:complexType name="withinTextRule.type"> <xs:attributeGroup ref="its:its.Selector.attlist"/> <xs:attribute name="withinText" type="its:withinText.type"/> </xs:complexType> </xs:schema> The following is a driver file which can be used to evoke the schema above. <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xhtml="http://www.w3.org/1999/xhtml" targetNamespace="http://www.w3.org/1999/xhtml" xmlns:its="http://www.w3.org/2005/11/its" xmlns="http://www.w3.org/1999/xhtml" blockDefault="#all"> <xs:annotation> <xs:documentation> This is the XML Schema Driver for new Document Type XHTML Basic 1.0 + ITS $Id: Overview.html,v 1.12 2018/10/09 13:20:06 denis Exp $ </xs:documentation> <xs:documentation source="http://www.w3.org/TR/xml-i18n-bp/#integration-its-xhtmlmod"/> </xs:annotation> <xs:import namespace="http://www.w3.org/2005/11/its" schemaLocation="its-module.xsd"/> <xs:redefine schemaLocation="xhtml-schemas/xhtml-basic10.xsd"> <xs:group name="HeadOpts.mix"> <xs:choice> <xs:group ref="HeadOpts.mix"/> <xs:element ref="its:rules"/> </xs:choice> </xs:group> <xs:attributeGroup name="Common.attrib"> <xs:attributeGroup ref="Common.attrib"/> <xs:attributeGroup ref="its:its.ITSLocal.attlist"/> </xs:attributeGroup> </xs:redefine> </xs:schema> The file below is an instance which can be validated against this schema. <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:its="http://www.w3.org/2005/11/its"> <head> <title> </title> <its:rules version="1.0"> <its:locNoteRule locNoteType="alert" selector="..." locNoteRef="..."> </its:locNoteRule> <its:locNoteRule locNoteType="alert" selector="..."> <its:locNote> </its:locNote> </its:locNoteRule> <its:termRule selector="..." term="yes"/> </its:rules> </head> <body> <h3> </h3> <table> <tr> <td> </td> </tr> </table> <ul> <li its:locNote="..." its:translate="no"> </li> </ul> </body> </html> This schema conforms to Conformance Type 1 The schema adds the following ITS element to the XHTML schema: its:rules The schema adds the following local ITS attributes to the XHTML schema: its:translate its:locNote its:locNoteType its:locNoteRef its:term its:termInfoRef As you have seen in the previous section it might sometimes be quite laborious to integrate ITS into an existing vocabulary using only modularization and the customization features of particular schema language. In such situations you can use the NVDL schema language instead. In NVDL you can create a sort of "meta-schema" which defines how to combine and provide additional rules for existing schemas. An NVDL schema can be used in the same way as schemas written in other languages, such as DTDs, RELAX NG or XML Schema. You can then use such a schema to validate your document instances or so that an XML editor can guide you while you are editing documents. The NVDL.org site Adding ITS to XHTML involves allowing the its:rules head local attributes <?xml version="1.0" encoding="UTF-8"?> <rules xmlns="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0" startMode="xhtml">
<!-- Validation starts here --> <mode name="xhtml"> <!-- XHTML elements are validated against XHTML schema --> <namespace ns="http://www.w3.org/1999/xhtml"> <validate schema="../xhtml-schemas/xhtml11.xsd"> <!-- Inside head element its:rules element is allowed --> <context path="head" useMode="its-rules"/> </validate> </namespace>
<!-- ITS attributes are validated against separate schema --> <namespace ns="http://www.w3.org/2005/11/its" match="attributes"> <validate schema="its-attributes-for-xhtml.rng"/> </namespace> </mode>
<!-- Handling of ITS markup in head is different because its:rules should be allowed --> <mode name="its-rules"> <namespace ns="http://www.w3.org/2005/11/its"> <validate schema="its-rules.rng"/> </namespace> <namespace ns="http://www.w3.org/2005/11/its" match="attributes"> <validate schema="its-attributes-for-xhtml.rng"/> </namespace> </mode> </rules> [ Example's source code The NVDL script references three schemas. One for XHTML and two supplementary ones for ITS. The first supplementary schema defines local attributes which are needed for XHTML. <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0">
<!-- Include schema with all ITS building blocks --> <include href="its.rng"/> <!-- Pull out only definitions of ITS attributes which are useful for XHTML --> <start> <group> <ref name="its-att.translate.attributes"/> <ref name="its-att.locNote.attributes"/> <ref name="its-att.term.attributes"/> <optional> <ref name="its-att.version.attributes"/> </optional> </group> </start> </grammar> [ Example's source code The second supplementary schema defines the its:rules <?xml version="1.0" encoding="UTF-8"?> <grammar xmlns="http://relaxng.org/ns/structure/1.0">
<!-- Include schema with all ITS building blocks --> <include href="its.rng"/>
<!-- Pull out only definition of its:rules element --> <start> <ref name="its-rules"/> </start>
</grammar> [ Example's source code This schema conforms to Conformance Type 1 The schema adds the following ITS element to the XHTML schema: its:rules The schema adds the following local ITS attributes to the XHTML schema: its:translate its:locNote its:locNoteType its:locNoteRef its:term its:termInfoRef A number of XHTML constructs implement the same semantics as some of the ITS data categories. In addition, some of the attributes in XHTML need to be translated, which is not the default for XML documents according to the default translate settings in ITS An external ITS rules <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0" xmlns:h="http://www.w3.org/1999/xhtml">
<!-- special content. (See note 1) --> <its:translateRule selector="//h:script" translate="no"/> <its:translateRule selector="//h:style" translate="no"/>
<!-- Normal translatable attributes --> <its:translateRule selector="//h:*/@abbr" translate="yes"/> <its:translateRule selector="//h:*/@accesskey" translate="yes"/> <its:translateRule selector="//h:*/@alt" translate="yes"/>
<its:translateRule selector="//h:*/@prompt" translate="yes"/> <its:translateRule selector="//h:*/@standby" translate="yes"/> <its:translateRule selector="//h:*/@summary" translate="yes"/> <its:translateRule selector="//h:*/@title" translate="yes"/>
<!-- The input element (Important: See note 2) --> <its:translateRule selector="//h:input/@value" translate="yes"/> <its:translateRule selector="//h:input[@type='hidden']/@value" translate="no"/>
<!-- Non-translatable element (See note 3) -->
<its:translateRule selector="//h:del" translate="no"/> <its:translateRule selector="//h:del/descendant-or-self::*/@*" translate="no"/>
<!-- Often-used translatable meta content. --> <its:translateRule selector="//h:meta[@name='keywords']/@content" translate="yes"/> <its:translateRule selector="//h:meta[@name='description']/@content" translate="yes"/>
<!-- Possible term (Important: See note 4) --> <its:termRule selector="//h:dt" term="yes"/>
<!-- Bidirectional information --> <its:dirRule selector="//h:*[@dir='ltr']" dir="ltr"/> <its:dirRule selector="//h:*[@dir='rtl']" dir="rtl"/> <its:dirRule selector="//h:bdo[@dir='ltr']" dir="lro"/> <its:dirRule selector="//h:bdo[@dir='rtl']" dir="rlo"/>
<!-- Elements within text --> <its:withinTextRule withinText="yes" selector="//h:abbr | //h:acronym | //h:br | //h:cite | //h:code | //h:dfn | //h:kbd | //h:q | //h:samp | //h:span | //h:strong | //h:var | //h:b | //h:em | //h:big | //h:hr | //h:i | //h:small | //h:sub | //h:sup | //h:tt | //h:del | //h:ins | //h:bdo | //h:img | //h:a | //h:font | //h:center | //h:s | //h:strike | //h:u | //h:isindex" />
</its:rules> [ Example's source code Additional notes on these rules: The script style The value input value The del img alt selector="//h:del/descendant-or-self::*/@*" del The dt ITS Terminology data category dt The Text Encoding Initiative [TEI] TEI is maintained as a single ODD document, and customizations of it are also written as ODD documents. ODD ( One Document Does it all The ITS additions involve two changes to TEI: Allowing rules teiHeader Adding the ITS local attributes Both of these can be easily achieved using standard techniques in ODD. The body of a TEI+ITS customization consists of a schemaSpec schemaSpec <schemaSpec ident="tei-its" start="TEI"> <moduleRef key="header"/> <moduleRef key="core"/> <moduleRef key="tei"/> <moduleRef key="textstructure"/> <moduleRef key="namesdates"/> <moduleRef key="msdescription"/> <!-- Etc. --> </schemaSpec> [ Example's source code In addition, we load the ITS schema (in its RELAX NG XML format, the language used by TEI for expressing content models), and overload the definition of the TEI content class model.headerPart rules rules <moduleRef url="its.rng"> <content xmlns:rng="http://relaxng.org/ns/structure/1.0"> <rng:define name="model.headerPart" combine="choice"> <rng:ref name="rules"/> </rng:define> </content> </moduleRef> [ Example's source code The content class determines which elements are allowed as children of teiHeader att.global local attributes <classSpec ident="att.global" type="atts" mode="change"> <attList> <attRef name="span.attributes"/> </attList> </classSpec> [ Example's source code When processing, this customization produces a schema which permits markup like this: <TEI xmlns:its="http://www.w3.org/2005/11/its" xmlns="http://www.tei-c.org/ns/1.0"> <teiHeader> <fileDesc> <!-- details of the file --> </fileDesc> <rules xmlns="http://www.w3.org/2005/11/its" version="1.0" xmlns:t="http://www.tei-c.org/ns/1.0"> <translateRule translate="no" selector="//t:body/t:p/@*"/> <translateRule translate="yes" selector="//t:body/t:p"/> </rules> </teiHeader> <text> <body> <p rend="normal">Hello <hi>world</hi> </p> <p rend="special">Goodbye</p> <p its:translate="no">This must not be translated</p> </body> </text> </TEI> [ Example's source code In this example, a set of rule elements are provided in the header to provide rules, and the body of the text performs a specific override. This schema conforms to Conformance Type 1 The schema adds the following ITS element to the TEI schema: its:rules The schema adds the following local ITS attributes to the TEI schema: its:translate its:locNote its:locNoteType its:locNoteRef its:term its:termInfoRef The XML Spec format [XML Spec] The text below takes version 2.10 of XML Spec DTD XML Schema RELAX NG Note: W3C Internationalization Activity modified version of the XML Spec 2.9 DTD The integration of ITS into the XML Spec DTD xmlspec-its.dtd its.dtd External ITS definitions are integrated via the new entity <!ENTITY % its SYSTEM "its.dtd"> %its; The existing XML Spec entity %local.common.att; '%its.att.local.with-ns.attributes; xmlns:its CDATA "http://www.w3.org/2005/11/its" local attributes The XML Spec entity %header.mdl; header its:rules its:rules The ITS elements its:ruby its:span %p.pcd.mix; The integration of ITS into the XML Spec RELAX NG schema xmlspec-its.rnc its.rnc External ITS definitions are integrated via the statement include "its.rnc" The pattern its-att.local.with-ns.attributes local.common.att The pattern its-rules header.mdl The patterns its-ruby its-span p.pcd.mix The integration of ITS into the XML Spec XML Schema schema xmlspec-its.xsd its.xsd xml.xsd XML namespace xlink.xsd XLink namespace External ITS definitions are integrated via an <xs:import> The attribute group its-att.local.with-ns.attributes common.att The element declaration its:rules header.mdl The element declarations its:ruby its:span p.pcd.mix The following example shows an XML Spec document conforming to the XML Spec+ITS schemas. The its:translateRule w3c-doctype <?xml version="1.0" encoding="UTF-8"?> <spec xmlns:its="http://www.w3.org/2005/11/its"> <header> <title>Best Practices for XML Internationalization</title> <w3c-designation>...</w3c-designation> <w3c-doctype its:translate="no">W3C Working Draft</w3c-doctype> <pubdate> <day>5</day> <month>December</month> <year>2007</year> </pubdate> <publoc> <loc href="..." >...</loc> </publoc> <latestloc> <loc href="...">...</loc> </latestloc> <prevlocs> <loc href="..." >...</loc> </prevlocs> <authlist> <author> <name>...</name> <affiliation>...</affiliation> </author> </authlist> <abstract> <p>This document provides a set of guidelines for ...</p> </abstract> <status> <p/> </status> <langusage> <language id="en">en</language> </langusage> <revisiondesc> <p>This is an updated version of this document.</p> </revisiondesc> <its:rules version="1.0"> <its:translateRule selector="//code | //kw //eg" translate="no"/> </its:rules> </header> <body> <div1 id="idIntro"> <head>Introduction</head> <p>This document is a complement ...</p> </div1> </body> <back> <div1> <head>References</head> </div1> <inform-div1> <head>Acknowledgements</head> </inform-div1> </back> </spec> [ Example's source code The three XML Spec schemas described above conform to Conformance Type 1 The following ITS elements are added: its:rules its:ruby its:span The following local ITS attributes are added: its:translate its:locNote its:locNoteType its:locNoteRef its:term its:termInfoRef A number of XML Spec constructs implement the same semantics as some of the ITS data categories. In addition, some of the XML Spec attribute values need to be translated, which is not the default for XML documents according to the ITS default settings for translatability Note: An external ITS its:rules <its:rules xmlns:its="http://www.w3.org/2005/11/its" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0"> <!-- Translatable attributes --> <its:translateRule selector="//graphic/@alt | //table/@summary | //term | //termdef | //key-term" translate="yes"/>
<!-- Non-translatable elements/attributes --> <its:translateRule translate="no" selector="//version | // w3c-designation | w3c-doctype | //publoc | //altlocs | //prevlocs | //latestloc | //errataloc | //preverrataloc | //translationloc | //authlist | //author | //name | //affiliation | //email | //langusage | //language | //graphic | //proto | //arg | //scrap | //prodgroup | //prod | //lhs | //rhs | //wfc | //vc | //constraint | //bnf | //prodrecap | //interface | //module | //reference | //typedef | // struct | //component | //union | //case | //enum | //enumerator | //sequence | //constant | //exception | //attribute | //method | //parameters | //param | //returns | //raises | //typename | //att | //attval | //bibref | //code | //el | //kw | //nt | //var | //xnt | //key-term"/>
<!-- Possible terms --> <its:termRule selector="//label | //def" term="yes"/>
<!-- Elements within text --> <its:withinTextRule withinText="yes" selector="//abbr | //att | //attval | //code | //eg | //emph | //ins | //kw | //loc | //note | //qterm | //phrase | //quote"/> <its:withinTextRule withinText="nested" selector="//footnote | //termdef | //its:ruby"/>
</its:rules> [ Example's source code The Darwin Information Typing Architecture [DITA 1.0] DITA offers some of the ITS features by default (See Section 5.4.2: Associating existing DITA markup with ITS its:locNote its:rules foreign For example, the DITA Concept DTD can be extended as follows: First, create two files for the ITS domain specialization. The first one itsDomain.ent itsDomain.ent <?xml version="1.0" encoding="UTF-8"?> <!ENTITY % its-d-foreign "its" > <!ENTITY its-d-att "(topic its-d)" > [ Example's source code The second file, itsDomain.mod itsDomain.mod <?xml version="1.0" encoding="UTF-8"?> <!-- declaration for the specialized wrapper and alternate element --> <!ENTITY % its "its">
<!-- definition for the specialized wrapper and alternate element --> <!ELEMENT its ((%its-rules;) | (%its-ruby;)) > <!ATTLIST its %global-atts; class CDATA "+ topic/foreign its-d/its "> [ Example's source code Then you can adapt the concept.dtd Include the ITS domain entities at the end of the Domain Entity Declarations section: <!ENTITY % its-d-dec SYSTEM "itsDomain.ent" > %its-d-dec; Include the ITS document type and namespace: <!ENTITY % its-def SYSTEM "its.dtd" > %its-def; <!ENTITY % its-d-namespace "xmlns:its CDATA #FIXED 'http://www.w3.org/2005/11/its'"> <!ENTITY % props-attribute-extensions "" > <!ENTITY % base-attribute-extensions "%its-d-namespace; %att.version.attributes; %att.locNote.attributes;" > Define the extension element at the end of the Domain Extension section: <!ENTITY % foreign "foreign | %its-d-foreign;" > Modify the list of included domains in the included-domains entity: <!ENTITY included-domains "&ui-d-att; &hi-d-att; &pr-d-att; &sw-d-att; &ut-d-att; &indexing-d-att; &its-d-att;" > Include the ITS domain module at the end of the Domain Element Integration section: <!ENTITY % its-d-def SYSTEM "itsDomain.mod" > %its-d-def; [ Example's source code All these changes allow you to include a new its This DITA document includes the following ITS constructs: An its:rules prolog uicontrol The second p its:locNote The last paragraph includes an its:ruby <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "dtd/itsConcept.dtd"> <concept id="DITAwithITS" xml:lang="en" xmlns:its="http://www.w3.org/2005/11/its" its:version="1.0"> <title>Using ITS in DITA</title> <prolog> <its> <its:rules> <its:translateRule selector="ui" translate="no"/> </its:rules> </its> </prolog> <conbody xml:lang="ja"> <p>Example of applying global rules: Normal text with <uicontrol>non-translatable text</uicontrol>.</p> <p its:locNote="Localization note">Text where the note applies.</p> <p>Example of ruby text: <ph xml:lang="ja">この本は <its><its:ruby> <its:rb>慶応義塾大学</its:rb> <its:rp>(</its:rp> <its:rt>けいおうぎじゅくだいがく</its:rt> <its:rp>)</its:rp> </its:ruby></its>/の歴史を説明するものです。</ph> </p> </conbody> </concept> [ Example's source code This schema conforms to Conformance Type 1 The schema adds the following ITS element to the DITA DTD: its:rules its:ruby The schema adds the following local ITS attributes to the DITA DTD: its:locNote its:locNoteRef its:locNoteType its:version There are several ITS data categories that are already implemented in DITA. For example, DITA offers a translate its:translate In the same way as for other formats, these existing features can be associated with ITS data categories, so ITS-enabled tools can process seamlessly DITA source documents. Note: <?xml version="1.0"?> <!-- Possible default ITS rules for DITA --> <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0">
<!-- Translatable attribute (some are deprecated) --> <its:translateRule selector="//image/@alt" translate="yes"/> <its:translateRule selector="//lq/@reftitle" translate="yes"/> <its:translateRule selector="//note/@othertype" translate="yes"/> <its:translateRule selector="//object/@standby" translate="yes"/> <its:translateRule selector="//othermeta/@content" translate="yes"/> <its:translateRule selector="//state/@value" translate="yes"/> <its:translateRule selector="//map/@title" translate="yes"/> <its:translateRule selector="//topicref/@navref" translate="yes"/> <its:translateRule selector="//topicgroup/@navtitle" translate="yes"/> <its:translateRule selector="//topichead/@navtitle" translate="yes"/> <its:translateRule selector="//data/@label" translate="yes"/>
<!-- Non-translatable elements --> <its:translateRule selector="//draft-comment//*" translate="no"/> <its:translateRule selector="//draft-comment/descendant-or-self::*/@*" translate="no"/> <its:translateRule selector="//required-cleanup//*" translate="no"/> <its:translateRule selector="//required-cleanup/descendant-or-self::*/@*" translate="no"/> <its:translateRule selector="//coords" translate="no"/> <its:translateRule selector="//shape" translate="no"/>
<!-- Translatability flags --> <its:translateRule selector="//*[@translate='no']" translate="no"/> <its:translateRule selector="//*[@translate='no']/descendant-or-self::*/@*" translate="no"/> <its:translateRule selector="//*[@translate='yes']" translate="yes"/>
<!-- Directionality flags --> <its:dirRule selector="//*[dir='ltr']" dir="ltr"/> <its:dirRule selector="//*[dir='rtl']" dir="rtl"/> <its:dirRule selector="//*[dir='lro']" dir="lro"/> <its:dirRule selector="//*[dir='rlo']" dir="rlo"/>
<!-- Elements within text (inline) --> <its:withinTextRule withinText="yes" selector="//boolean | //cite | //itemgroup | //keyword | //ph | //q | //state | //term | //tm | //xref | //b | //i | //sub | //sup | //tt | //u | //apiname | //codeph | //delim | //fragref | //kwd | //oper | //option | //parmname | //repsep | //sep | //synnoteref | //synph | //var | //cmdname | //filepath | //msgnum | //msgph | //systemoutput | //userinput | //varname | //menucascade | //shortcut | //uicontrol | //wintitle | //coords | //shape" />
<!-- The keyword elements within keywords are sub-flow, no in-line --> <its:withinTextRule withinText="nested" selector="//keywords/keyword" />
<!-- Elements within text (subflow) --> <its:withinTextRule withinText="nested" selector="//draft-comments | //required-cleanup | //alt | //fn | //indexterm" />
<!-- Terminology --> <its:termRule selector="//term | //dt | //termindex" term="yes" />
</its:rules> [ Example's source code The declarations above cover different versions of DITA. Glade [Glade] <?xml version="1.0" standalone="no"?><!--*- mode: xml -*--> <glade-interface> <widget class="GtkWindow" id="main_window"> <property name="visible">True</property> <property name="title" translatable="yes">Glade Text Editor</property> <property name="type">GTK_WINDOW_TOPLEVEL</property> <property name="window_position">GTK_WIN_POS_NONE</property> <property name="modal">False</property> <property name="default_width">600</property> <property name="default_height">450</property> <property name="resizable">True</property> <property name="destroy_with_parent">False</property> <property name="decorated">True</property> <property name="skip_taskbar_hint">False</property> <property name="skip_pager_hint">False</property> <property name="type_hint">GDK_WINDOW_TYPE_HINT_NORMAL</property> <property name="gravity">GDK_GRAVITY_NORTH_WEST</property> <property name="focus_on_map">True</property> <property name="urgency_hint">False</property> <signal name="delete_event" handler="on_main_window_delete_event"/> <child> <widget class="GtkVBox" id="vbox1"> <property name="visible">True</property> <property name="homogeneous">False</property> <property name="spacing">0</property> <child> <widget class="GtkHandleBox" id="handlebox2"> <property name="visible">True</property> <property name="shadow_type">GTK_SHADOW_OUT</property> <property name="handle_position">GTK_POS_LEFT</property> <property name="snap_edge">GTK_POS_TOP</property> <child> <widget class="GtkMenuBar" id="menubar1"> <property name="visible">True</property> <property name="pack_direction">GTK_PACK_DIRECTION_LTR</property> <property name="child_pack_direction">GTK_PACK_DIRECTION_LTR</property> <child> <widget class="GtkMenuItem" id="File"> <property name="visible">True</property> <property name="label" translatable="yes">_File</property> <property name="use_underline">True</property> <child> <widget class="GtkMenu" id="File_menu"> <child> <widget class="GtkImageMenuItem" id="Open"> <property name="visible">True</property> <property name="label">gtk-open</property> <property name="use_stock">True</property> <signal name="activate" handler="on_Open_activate"/> </widget> </child> <child> <widget class="GtkImageMenuItem" id="Exit"> <property name="visible">True</property> <property name="label">gtk-quit</property> <property name="use_stock">True</property> <signal name="activate" handler="on_Exit_activate"/> </widget> </child> </widget> </child> </widget> </child> </widget> </child> </widget> <packing> <property name="padding">0</property> <property name="expand">False</property> <property name="fill">True</property> </packing> </child> </widget> </child> </widget> </glade-interface> [ Example's source code The content of the GladeXML files are mostly composed of data that should not be translated: user-interface widgets properties. Text content is limited to titles, labels and a few various other types of strings. GladeXML does offer support for some of the ITS features, but not all of them. While it would be technically feasible to allow the use of additional ITS markup directly in your GladeXML resources, there is little point doing it here because these resources are closely tied to the Glade's editors and compilers which would have to be modified as well. GladeXML offers a translatable its:translate comments Like for other formats, existing features of GladeXML can be associated with ITS data categories using global rules, so ITS-enabled tools can seamlessly process GladeXML source documents. <its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"> <!-- ITS rules for Glade 2.0, based on http://glade.gnome.org/glade-2.0.dtd --> <its:translateRule selector="/glade-interface" translate="no"/> <its:translateRule selector="//*[@translatable='yes']" translate="yes"/> <its:translateRule selector="//atkaction/@description" translate="yes"/> <its:locNoteRule selector="//*[@translatable='yes']" locNoteType="description" locNotePointer="@comments"/> </its:rules> [ Example's source code DocBook is a general purpose XML schema particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications). DocBook is maintained by the DocBook Technical Committee OASIS DocBook V5.0 schema is maintained as a very modular and easy to customize schema written in RELAX NG [RELAX NG 1.0] [DocBook V5.0 HOWTO] The ITS additions involve the following changes to the DocBook schema: Adding the ITS local attributes Not all ITS local attributes are added to the schema, as DocBook already provides its own means for specifying directionality of text. Such existing markup should be associated with ITS data categories using its:rules Section 5.6.2: Associating existing DocBook markup with ITS Allowing the its:rules info Allowing the its:ruby # This schema integrates ITS markup (http://www.w3.org/TR/its/) # into DocBook schema (http://docbook.org) # # This schema conforms to Conformance Type 1 defined in # http://www.w3.org/TR/its/#conformance-product-schema # # Schema adds the following ITS elements into DocBook schema: # * rules # * ruby # # Schema adds the following local ITS attributes into DocBook schema: # * translate # * locNote # * locNoteType # * locNoteRef # * term # * termInfoRef
# Namespace declarations for DocBook, ITS and HTML # (HTML is used internally in DocBook schema) namespace db = "http://docbook.org/ns/docbook" namespace its = "http://www.w3.org/2005/11/its" namespace html = "http://www.w3.org/1999/xhtml"
# Include base DocBook schema include "docbook.rnc" { # Exclude ITS markup from "wildcard" element db._any = element * - (db:* | html:* | its:*) { (attribute * { text } | text | db._any)* } }
# Include base ITS schema include "its.rnc"
# Define pattern for local ITS attributes db.its.attributes = its-att.translate.attributes? & its-att.locNote.attributes? & its-att.term.attributes? & its-att.version.attributes?
# Add local ITS attributes to all DocBook elements db.common.base.attributes &= db.its.attributes
# Allow its:rules inside info element db.info.extension |= its-rules
# Allow Ruby markup almost everywhere db.ubiq.inlines |= its-ruby [ Example's source code For your convenience there is also available a “flattened” schema stored inside one file. dbits.rnc dbits.rng There is no need to add the its:span phrase The following example shows a sample DocBook article conforming to the DocBook+ITS schema. The its:translateRule function <?xml version="1.0" encoding="UTF-8"?> <article xmlns="http://docbook.org/ns/docbook" xmlns:its="http://www.w3.org/2005/11/its" xmlns:db="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"> <info> <title>Sample article</title> <its:rules version="1.0"> <its:translateRule translate="no" selector="//db:function"/> </its:rules> </info> <para its:translate="no">Non-translatable content</para> <section> <title>Sample section</title> <para>You can delete file using <function>unlink()</function> function.</para> </section> </article> [ Example's source code This schema conforms to Conformance Type 1 The schema adds the following ITS elements to the DocBook schema: its:rules its:ruby The schema adds the following local ITS attributes to the DocBook schema: its:translate its:locNote its:locNoteType its:locNoteRef its:term its:termInfoRef A number of DocBook constructs implement the same semantics as some of the ITS data categories. In addition, some of the DocBook attributes have values which should be translated, which is not the default for XML documents according to the ITS default settings Note: An external ITS its:rules <its:rules xmlns:its="http://www.w3.org/2005/11/its" xmlns:db="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0">
<!-- Translatable attributes --> <its:translateRule selector="//db:table/@summary" translate="yes"/> <its:translateRule selector="//db:*/@xlink:title" translate="yes"/> <its:translateRule selector="//db:*/@xreflabel" translate="yes"/> <its:translateRule selector="//db:*/@label" translate="yes"/>
<!-- Non-translatable elements/attributes --> <its:translateRule translate="no" selector="//db:*[@revisionflag = 'deleted']"/> <its:translateRule translate="no" selector="//db:*[@revisionflag = 'deleted']//@*"/> <its:translateRule translate="no" selector="//db:acronym | //db:author | //db:classname | //db:command | //db:constant | //db:date | //db:editor | //db:email | //db:envar | //db:errorcode | //db:exceptionname | //db:filename | //db:function | //db:initializer | //db:interfacename | //db:markup | //db:methodname | //db:modifier | //db:ooclass | //db:ooexception | //db:oointerface | //db:option | //db:parameter | //db:person | //db:personname | //db:productnumber | //db:property | //db:returnvalue | //db:symbol | //db:tag | //db:type | //db:uri | //db:varname"/>
<!-- Possible terms --> <its:termRule selector="//db:glossterm" term="yes"/> <its:termRule selector="//db:firstterm" term="yes"/> <its:termRule selector="//db:abbrev" term="yes"/> <its:termRule selector="//db:acronym" term="yes"/>
<!-- Bidirectional information --> <its:dirRule selector="//db:*[@dir='ltr']" dir="ltr"/> <its:dirRule selector="//db:*[@dir='rtl']" dir="rtl"/> <its:dirRule selector="//db:*[@dir='lro']" dir="lro"/> <its:dirRule selector="//db:*[@dir='rlo']" dir="rlo"/>
<!-- Elements within text --> <its:withinTextRule withinText="yes" selector="//db:abbrev | //db:accel | //db:acronym | //db:application | //db:author | //db:citation | //db:citebiblioid | //db:citerefentry | //db:citetitle | //db:classname | //db:code | //db:command | //db:computeroutput | //db:constant | //db:database | //db:date | //db:editor | //db:email | //db:emphasis | //db:envar | //db:errorcode | //db:errorname | //db:errortext | //db:errortype | //db:exceptionname | //db:filename | //db:foreignphrase | //db:function | //db:guibutton | //db:guiicon | //db:guilabel | //db:guimenu | //db:guimenuitem | //db:guisubmenu | //db:hardware | //db:initializer | //db:interfacename | //db:jobtitle | //db:keycap | //db:keycode | //db:keycombo | //db:keysym | //db:link | //db:literal | //db:markup | //db:menuchoice | //db:methodname | //db:modifier | //db:mousebutton | //db:olink | //db:ooclass | //db:ooexception | //db:oointerface | //db:option | //db:optional | //db:org | //db:orgname | //db:package | //db:parameter | //db:person | //db:personname | //db:phrase | //db:productname | //db:productnumber | //db:prompt | //db:property | //db:quote | //db:replaceable | //db:returnvalue | //db:shortcut | //db:subscript | //db:superscript | //db:symbol | //db:systemitem | //db:tag | //db:token | //db:trademark | //db:type | //db:uri | //db:userinput | //db:varname | //db:wordasword"/>
<its:withinTextRule withinText="nested" selector="//db:alt | //db:footnote | //db:remark | //db:indexterm | //db:primary | //db:secondary | //db:tertiary"/>
</its:rules> [ Example's source code Addison Phillips and Mark Davis, editors. Tags for Identifying Languages http://www.rfc-editor.org/rfc/bcp/bcp47.txt Richard Ishida, editor. Internationalization Best Practices: Handling Right-to-left Scripts in XHTML and HTML Content http://www.w3.org/TR/2007/WD-i18n-html-tech-bidi-20070606/ Bidi in X/HTML Martin J. Dürst, François Yergeau, Richard Ishida, Misha Wolf, Tex Texin, editors. Character Model for the World Wide Web 1.0: Fundamentals http://www.w3.org/TR/2005/REC-charmod-20050215/ CharMod Michael Priestley, JoAnn Hackos, et. al., editors. OASIS Darwin Information Typing Architecture (DITA) Language Specification v1.0 http://www.oasis-open.org/committees/download.php/15316/dita10.zip Jirka Kosek, Norman Walsh and Dick Hamilton. DocBook V5.0: The Transition Guide http://docbook.org/docs/howto/ Glade - a User Interface Builder for GTK+ and GNOME http://glade.gnome.org/ Christian Lieske and Felix Sasaki, editors. Internationalization Tag Set (ITS) Version 1.0 http://www.w3.org/TR/2007/REC-its-20070403/ ITS Yves Savourel, editor. Internationalization and Localization Markup Requirements http://www.w3.org/TR/2006/WD-itsreq-20060518/ ITS REQ Information technology -- Document Schema Definition Languages (DSDL) -- Part 4: Namespace-based Validation Dispatching Language (NVDL). Information technology – Document Schema Definition Language (DSDL) – Part 2: Regular-grammar-based validation – RELAX NG. Marcin Sawicki, Michel Suignard, Masayasu Ishikawa, et al. editors. Ruby Annotation http://www.w3.org/TR/2001/REC-ruby-20010531/ Ruby Annotation Lou Burnard and Syd Bauman, editors. Text Encoding Initiative Guidelines development version (P5) Martin Dürst and Asmus Freytag. Unicode in XML and other Markup Languages Unicode in XML Steven Pemperton et al., editors. XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition) http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 Daniel Austin et al., editors. XHTML™ Modularization 1.1 http://www.w3.org/TR/2006/WD-xhtml-modularization-20060705/ XHTMLMod1.1 Jonathan Marsh, David Orchard and Daniel Veillard, editors. - XML Inclusions (XInclude) Version 1.0 (Second Edition) http://www.w3.org/TR/2006/REC-xinclude-20061115/ XInclude 1.0 Yves Savourel et al., editors. XLIFF Version 1.2 http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core.html XLIFF 1.2 Steve DeRose, Eve Maler and David Orchard, editors. - XML Linking Language 1.0 http://www.w3.org/TR/2001/REC-xlink-20010627/ XLink 1.0 Jonathan Marsh, Daniel Veillard and Norman Walsh, editors. - xml:id Version 1.0 http://www.w3.org/TR/2005/REC-xml-id-20050909/ xml:id Tim Bray, Dave Hollander and Andrew Layman, editors. Namespaces in XML http://www.w3.org/TR/1999/REC-xml-names-19990114/ XML Names The XML Spec Schema and Stylesheets This document has been developed with important contributions from past and present member of the Working Group: Bartosz Bogacki (W3C Invited Expert), Martin Dürst (W3C Invited Expert), Tim Foster, Richard Ishida (W3C/ERCIM), Masaki Itagaki, Jirka Kosek (W3C Invited Expert), Christian Lieske (SAP AG), Sebastian Rahtz (W3C Invited Expert), Felix Sasaki (W3C/Keio), Yves Savourel (ENLASO Corporation), Diane Stoick (The Boeing Company), Najib Tounsi (Ecole Mohammadia d'Ingenieurs Rabat (EMI)), and Andrzej Zydron. At the date of publication, the members of the Working Group were: Bartosz Bogacki (W3C Invited Expert), Damien Donlon (Sun Microsystems, Inc.), Martin Dürst (W3C Invited Expert), Poonam Gupta (Centre for Development of Advanced Computing (CDAC)), Richard Ishida (W3C/ERCIM), Jirka Kosek (W3C Invited Expert), Christian Lieske (SAP AG), Sebastian Rahtz (W3C Invited Expert), Francois Richard (HP), Goutam Saha (Centre for Development of Advanced Computing (CDAC)), Felix Sasaki (W3C/Keio), Yves Savourel (ENLASO Corporation), Diane Stoick (The Boeing Company), and Najib Tounsi (Ecole Mohammadia d'Ingenieurs Rabat (EMI)).