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 thexml: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".
<?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>
<?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>