The @xml:lang attribute

The @xml:lang attribute specifies the language and (optional) locale of the element content. The @xml:lang attribute applies to all attributes and content of the element where it is specified, unless it is overridden with @xml:lang on another element within that content.

The @xml:lang attribute SHOULD be explicitly set on the root element of each map and topic.

Setting the @xml:lang attribute in the DITA source ensures that processors handle content in a language- and locale-appropriate way. If the @xml:lang attribute is not set, processors assume a default value which might not be appropriate for the DITA content. When the @xml:lang attribute is specified for a document, DITA processors MUST use the specified value to determine the language of the document.

Setting the @xml:lang attribute in the source language document facilitates the translation process; it enables translation tools (or translators) to simply change the value of the existing @xml:lang attribute to the value of the target language. Some translation tools support changing the value of an existing @xml:lang attribute, but they do not support adding new markup to the document that is being translated. Therefore, if source language content does not set the @xml:lang attribute, it might be difficult or impossible for the translator to add the @xml:lang attribute to the translated document.

If the root element of a map or a top-level topic has no value for the@xml:lang attribute , a processor SHOULD assume a default value. The default value of the processor can be either fixed, configurable, or derived from the content itself, such as the @xml:lang attribute on the root map.

The @xml:lang attribute is described in the XML Recommendation. Note that the recommended style for the @xml:lang attribute is lowercase language and (optional) uppercase, separated by a hyphen, for example, "en-US" or "sp-SP" or "fr". According to RFC 5646, Tags for Identifying Languages, language codes are case insensitive.

Recommended use in topics

For a DITA topic that contains a single language, set the @xml:lang attribute on the highest-level element that contains content.

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

Recommended use in maps

The @xml:lang attribute can be specified on the <map> element. The @xml:lang attribute cascades within the map in the same way that it cascades within a topic. However, since the @xml:lang attribute is an inherent property of the XML document, the value of the @xml:lang attribute does not cascade from one map to another or from a map to a topic; the value of the @xml:lang attribute that is specified in a map does not override @xml:lang values that are specified in other maps or in topics.

The primary language for the map SHOULD be set on the <map> element. The specified language remains 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.

Recommended 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 referenced element does not have an explicit value for the @xml:lang attribute, 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 that sets the @xml:lang attribute to "fr". When the installingAcme.dita topic is processed, the <note> element with the @id attribute set to "mynote" has an effective value for the @xml:lang attribute of "fr".

Figure 1. installingAcme.dita
<?xml version="1.0"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task xml:lang="en" id="install_acme">
 <title>Installing Acme</title>
 <shortdesc>Step-by-step details about how to install Acme.</shortdesc>
 <taskbody>
   <prereq>
   <p>Special notes when installing Acme in France:</p>
   <note id="mynote" conref="warningsAcme.dita#topic_warnings/frenchwarnings"/>
  </prereq>
 </taskbody>
</task>
Figure 2. 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>