Skip to main content
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:
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.

​
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:
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).

​
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.