2.1.3.9.1 The @xml:lang attribute

The @xml:lang attribute is described in the XML Recommendation at http://www.w3.org/TR/REC-xml/#sec-lang-tag. Note that the recommended style for the @xml:lang attribute is lower case language and uppercase locale (if used), separated by a hyphen, i.e., en-US or sp-SP.

Recommended use in topics

For a DITA document that contains a single language, the highest level element that contains content should set the @xml:lang attribute to the language (and optionally the locale) that applies to the document. It is highly recommended that the @xml:lang attribute be set in all source-language topics to allow for its simple change in target-language topics.

When a DITA document contains more than one language, the highest level element should set the @xml:lang attribute to the primary language (and optionally the locale) that applies to the document. If part of a document is written in a different language, authors should ensure that the part is enclosed in an element with the @xml:lang attribute set appropriately. Processors should style each element in a way that is appropriate for its language as identified by the @xml:lang attribute. This method of overriding the default document language applies to both block and inline elements that use the alternate language.

Using markup to identify language is strongly recommended to make the document as portable as possible. The marked-up document can be read and understood by humans. Because the boundaries of each language are clear, it is much easier for the author to update the document.

Applications should ensure that every highest level topic element explicitly assigns the @xml:lang attribute. Authors are urged to set the @xml:lang attribute in the source language so that the translator may change it in the target language. Because some translation software does not permite translators to add elements, the absence of the @xml:lang element from the source language may result in higher administrative costs for translation.

Use in maps

The @xml:lang attribute can be specified on the <map> element. The @xml:lang attribute cascades within the map the same way that it cascades within a topic. The @xml:lang value does not cascade from one map to another or from a map to a topic, and an @xml:lang value specified in a map does not override @xml:lang values specified in other maps or in topics.

The primary language for the map should be set on the <map> element; if it is not explicitly specified, the application should assume the default value. The specified language should remain in effect for all child <topicref> elements, unless a child specifies a different value for the @xml:lang attribute.

When no @xml:lang value is supplied locally or on an ancestor, a processor determined default value is assumed.

Use with the @conref or @conkeyref attribute

When a @conref or @conkeyref attribute is used to include content from one element into another, the processor must use the effective value of the @xml:lang attribute from the referenced element, that is, the element that contains the content. If the reference element does not have an explicit value for the @xml:lang attribute, the effective value for its @xml:lang attribute is determined by using the standard @xml:lang inheritance from the referenced source.. If this action results in no effective value for @xml:lang, the processor should default to using the same value that is used for topics that do not set the @xml:lang attribute.

This behavior is shown in the following example, where the value of the @xml:lang attribute of the included note is obtained from its parent <section> element (id="qqwwee") that sets the @xml:lang attribute. In this example, the @xml:lang value "fr" is applied to the note with the id attribute "mynote".

<-- ****************installingAcme.dita********************* -->
                
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic xml:lang="en" id="install_acme">
 <title>Installing Acme</title>
 <shortdesc>Step-by-step details about how to install Acme.</shortdesc>
 <body>
  <section>
   <title>Before you begin</title>
   <p>Special notes when installing Acme in France:</p>
   <note conref="warningsAcme.dita#topic_warnings/frenchwarnings"></note>
  </section>
 </body>
</topic>
</dita>
*******************************************

<-- **************** warningsAcme.dita ********************* -->
<?xml version="1.0"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="topic_warnings">
 <title>Warnings</title>
 <body>
  <section id="qqwwee" xml:lang="fr">
   <title>French warnings</title>
   <p>These are our French warnings.</p>
   <note id="frenchwarnings">Note in French!</note>
  </section>
  <section xml:lang="en">
   <title>English warnings</title>
   <p>These are our English warnings.</p>
   <note id="englishwarnings">Note in English!</note>
  </section>
 </body>
</topic>
*************************************