The @xml:lang attribute
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
<?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>