XML

Translate the text of any XML document in place, keeping its declaration, comments, attributes and layout byte for byte.

The xml file handler translates the text of an XML document that no dedicated format covers, such as a content export, a help file or a custom resource format. It writes each translation into a copy of the source file, so the declaration, DOCTYPE, comments, processing instructions, attributes, namespaces and whitespace stay as they were. Only translated text, and the attributes you name, change.

Android resources, XLIFF and Apple plural dictionaries are XML too, but they have their own formats: Android, XLIFF and Apple stringsdict. Use those for such files, because they understand keys, plurals and the state of each translation.

Configure XML translation #

A file is translated as generic XML only when its files entry sets "format": "xml". The .xml extension alone selects no format, because an Android strings.xml uses the same extension. The CLI skips a .xml file whose entry names no format, with a message, and the GitHub App skips it:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}

This writes content/de/guide.xml and content/fr/guide.xml for content/en/guide.xml. Target paths follow the same rules as JSON, described under output paths, and targetPath declares any other layout. A file belongs to the first entry whose pattern selects it, so keep Android resources in their own entry with "format": "android", and give the xml entry a pattern that does not reach them. The same configuration works in the CLI and the GitHub App.

What is translated #

Each element that holds text is one unit. An element that holds only other elements, comments and whitespace has no unit of its own, and its child elements are read instead:

xml
<?xml version="1.0" encoding="UTF-8"?>
<help>
  <!-- shown on the settings page -->
  <topic id="sync">
    <title>Sync your files</title>
    <p>Click <b>Sync</b> to upload your <a href="/files">files</a> now.</p>
  </topic>
</help>

Here title is one unit and p is another. The comment, the id and the href are not sent for translation.

  • Inline elements. Text that has elements inside it, like the p above, is one unit for the whole sentence. The inline elements go to the model as placeholders it can move but not change, so the translation can put Sync and files where the target language needs them. Comments and processing instructions inside such text are kept in the same way.
  • Whitespace. Text made only of whitespace, such as the indentation between elements, is never sent. The whitespace around a text stays in the file, and the whitespace inside it is sent as it is. Whitespace that a translation adds around its text is dropped.
  • CDATA. A text that is a single CDATA section is translated and written back as a CDATA section. A CDATA section beside other text becomes part of that text and is written back escaped, which XML reads the same way.
  • References. &amp;, &lt;, &gt;, &quot;, &apos; and character references such as &#169; are decoded before translation. An entity declared in the DOCTYPE, such as &brand; or &product-name;, is protected like a placeholder and written back as it is.
  • Values that are not prose. A text that is only digits, a URL, an ISO date or a 22-character identifier of letters and digits is copied into every target instead of being translated.

Element names and paths are read exactly as written, case and namespace prefix included.

Translate attributes #

Attribute values are never translated unless translateComponentProps names them. A string names an attribute on every element; an object with component names it only on those elements:

json
{
  "pattern": "content/en/*.xml",
  "format": "xml",
  "translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}

This translates every title attribute and the label attribute of <item> elements. Names match exactly as written, so x:title and Title are other attributes. A blank value is skipped. Identifiers, links, xml:lang and namespace declarations are translated only if you name them, so naming one by mistake changes how the file is read.

How translations are written #

In translated text, &, < and > are escaped. In a translated attribute, &, < and the attribute's own quote character are escaped, and tabs and line breaks are written as character references so that XML keeps them. A ]]> in a translated CDATA section is split across two sections. Line breaks in a translation are written with the file's own line ending. Control characters that XML cannot hold are dropped from a translation.

When the declaration names an encoding other than UTF-8, such as encoding="ISO-8859-1", characters outside ASCII in a translation are written as character references, such as &#xE9; for é, so the target stays readable in that encoding. The file is read as UTF-8, so a file that declares another encoding and holds raw bytes for accented letters fails with the position of the first one, and nothing is written for it. Save it as UTF-8, or write those characters as references.

The handler does not change xml:lang or any other attribute that states the document's language. Update it in your build or name it in translateComponentProps if it holds text.

Keys and reuse #

Each unit is keyed by its element path, written like XPath: /help/topic/title, /list/item[2], or /menu/item[1]/@label for an attribute. A position appears only where an element has siblings of the same name. These keys identify units in the job and in Studio.

A unit keeps its existing translation while its text and its element path, positions aside, are unchanged since the last push, and while the translation keeps the source's inline elements, nested the same way. The translation may put them in another order, as the target language's word order often needs. A translated attribute of an inline element moves with its element. Inserting an element translates only the new element, and the elements after it keep their translations even though their positions changed. A translation whose inline elements no longer match the source's, for example because someone removed one or moved it inside another in the target, is translated again.

Options that do not apply #

XML has no key rules. The CLI and the GitHub App refuse an xml entry that sets lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale or translateFrontmatterFields, because the file would otherwise be translated as if the option were not set. lockedPatterns is refused as for every format other than Java properties.

lingo push --key skips xml files with a message and pushes the other selected files.

Invalid XML #

A file that is not well-formed XML fails with the line and column of the first problem, such as an unclosed or mismatched tag, a bare &, two root elements, or text outside the root element. When several tags are still open at the end of the file, the error names them instead. A file whose elements are nested more than 256 deep fails too. Nothing is written for that file, and an existing target stays as it is. A target that is not well-formed fails the same way, with its locale named. Fix the XML, then push again.