Translating XML

Learn how to translate XML content with the DeepL API while preserving its structure, and how to control sentence splitting.

To translate XML content, set the tag_handling parameter to xml. The API extracts the text from the XML structure, translates it, and places the translation back into the structure. Without tag_handling, tags are treated as regular text.

Set tag_handling_version to v2 to use the improved tag handling algorithm. For version details and defaults, see the tag_handling_version parameter.

Example request

curl -X POST https://api.deepl.com/v2/translate \
  --header "Content-Type: application/json" \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --data '{
    "text": ["Press <b>Continue</b> to advance."],
    "target_lang": "DE",
    "tag_handling": "xml",
    "tag_handling_version": "v2"
}'

Example response

{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Drücken Sie <b>„Weiter\",</b> um fortzufahren.",
      "tag_handling_version": "v2"
    }
  ]
}

Accounts that first used tag handling after December 1, 2025 default to v2. All other accounts default to v1 and need to set tag_handling_version=v2 explicitly. Results differ between versions, so test representative content before switching versions in production.

With v2, XML input is strictly parsed: invalid XML (for example, an unclosed tag) returns the error Tag handling parsing failed, please check input. Make sure your XML is well-formed and handle this error in your integration.

To translate HTML content, see Translating HTML.

Translate sentences with inline markup

Send marked-up text as is; tags stay attached to the words they wrap, and placeholder tags are placed next to the translation of the words that precede or follow them:

Basic Example

Request

Press <i>Continue</i> to advance to the next page.

Response

Drücken Sie <i>Weiter</i>, um zur nächsten Seite zu gelangen.

With Attributes

Request

<x id="17">Please welcome the participants</x> to today's meeting.

Response

<x id="17">Bitte begrüßen Sie die Teilnehmer</x> des heutigen Treffens.

Nested Tags

Request

The firm said it had been conducting an <a>internal <b>investigation</b></a> for several months.

Response

Das Unternehmen sagte, dass es seit mehreren Monaten eine <a>interne <b>Untersuchung</b></a>durchgeführt habe.

Placeholder Tag

Request

Artificial intelligence<a/> is already shaping our everyday<b></b> lives.

Response

Künstliche Intelligenz<a/> prägt bereits heute unseren Alltag<b></b>.

Exclude content from translation

List tags whose content should not be translated in the ignore_tags parameter. The example below uses ignore_tags=x to preserve the text between <x> and </x> as is:

Example: ignore \<x\> tag

Parameters

tag_handling=xml, ignore_tags=x

Request

Please open the page <x>Settings</x> to configure your system.

Response

Bitte öffnen Sie die Seite <x>Settings</x> um Ihr System zu konfigurieren.

Translate whole XML documents

Send complete XML files the same way, with split_sentences=nonewlines so that line breaks in the file don’t split sentences. Tags that contain text (here title and par) are treated as sentence boundaries, and the content of each is translated separately:

Example

Parameters

tag_handling=xml, split_sentences=nonewlines

Example request

<document>
  <meta>
    <title>A document's title</title>
  </meta>
  <content>
    <par>This is the first sentence. Followed by a second one.</par>
    <par>This is the third sentence.</par>
  </content>
</document>

Example response

<document>
  <meta>
    <title>Der Titel eines Dokuments</title>
  </meta>
  <content>
    <par>Das ist der erste Satz. Gefolgt von einem zweiten.</par>
    <par>Dies ist der dritte Satz.</par>
  </content>
</document>

Without split_sentences=nonewlines, a newline in the middle of a sentence causes each part to be translated separately, producing wrong results:

Incorrect translation due to new lines

Request

<div>She bought oat
biscuits.</div>

Response

<div>Sie kaufte Hafer
Kekse.</div>

The two parts of the sentence have been translated separately: “oat biscuits” became “Hafer Kekse” instead of “Haferkekse”.

Keep sentences together across tags

When a single sentence is spread across multiple text-bearing tags, list those tags in the non_splitting_tags parameter so the sentence is translated as a whole:

Restricted Splitting

Parameters

tag_handling=xml, non_splitting_tags=par

Request

<par>The firm said it had been </par><par> conducting an internal investigation.</par>

Response

<par>Die Firma sagte, dass sie</par><par> eine interne Untersuchung durchgeführt</par><par> habe</par><par>.</par>

The sentence is translated as a whole and the par tags are treated as markup. Because the translation of “had been” moved to another position in the German sentence, the tags are duplicated (which is expected here).

Without non_splitting_tags

Parameters

tag_handling=xml

Request

<par>The firm said it had been </par><par> conducting an internal investigation.</par>

Response

<par>Die Firma sagte, es sei eine gute Idee gewesen.</par><par> Durchführung einer internen Untersuchung.</par>

Each par element is translated separately, producing an incorrect translation.

Control sentence splitting manually

If automatic detection of the XML structure doesn’t yield good results for your files, turn it off with outline_detection=0 and list your structure tags in the splitting_tags parameter. The example below reproduces the automatic behavior for the document shown earlier:

Outline detection example

Parameters

tag_handling=xml, split_sentences=nonewlines, outline_detection=0, splitting_tags=par,title

Example request

<document>
  <meta>
    <title>A document's title</title>
  </meta>
  <content>
    <par>This is the first sentence. Followed by a second one.</par>
    <par>This is the third sentence.</par>
  </content>
</document>

Example response

<document>
  <meta>
    <title>Der Titel eines Dokuments</title>
  </meta>
  <content>
    <par>Das ist der erste Satz. Gefolgt von einem zweiten.</par>
    <par>Dies ist der dritte Satz.</par>
  </content>
</document>

This approach takes more setup but gives you full control over how the translation output is structured.