> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-docs-language-table-from-v3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/translate/request-translation).

```bash Example request theme={null}
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"
}'
```

```json Example response theme={null}
{
  "translations": [
    {
      "detected_source_language": "EN",
      "text": "Drücken Sie <b>„Weiter\",</b> um fortzufahren.",
      "tag_handling_version": "v2"
    }
  ]
}
```

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

To translate HTML content, see [Translating HTML](/docs/translate/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:

<Tabs>
  <Tab title="Basic Example">
    ```markup Request theme={null}
    Press <i>Continue</i> to advance to the next page.
    ```

    ```markup Response theme={null}
    Drücken Sie <i>Weiter</i>, um zur nächsten Seite zu gelangen.
    ```
  </Tab>

  <Tab title="With Attributes">
    ```markup Request theme={null}
    <x id="17">Please welcome the participants</x> to today's meeting.
    ```

    ```markup Response theme={null}
    <x id="17">Bitte begrüßen Sie die Teilnehmer</x> des heutigen Treffens.
    ```
  </Tab>

  <Tab title="Nested Tags">
    ```markup Request theme={null}
    The firm said it had been conducting an <a>internal <b>investigation</b></a> for several months.
    ```

    ```markup Response theme={null}
    Das Unternehmen sagte, dass es seit mehreren Monaten eine <a>interne <b>Untersuchung</b></a>durchgeführt habe.
    ```
  </Tab>

  <Tab title="Placeholder Tag">
    ```markup Request theme={null}
    Artificial intelligence<a/> is already shaping our everyday<b></b> lives.
    ```

    ```markup Response theme={null}
    Künstliche Intelligenz<a/> prägt bereits heute unseren Alltag<b></b>.
    ```
  </Tab>
</Tabs>

## 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:

<Card title="Example: ignore \<x\> tag">
  ```text Parameters theme={null}
  tag_handling=xml, ignore_tags=x
  ```

  ```markup Request theme={null}
  Please open the page <x>Settings</x> to configure your system.
  ```

  ```markup Response theme={null}
  Bitte öffnen Sie die Seite <x>Settings</x> um Ihr System zu konfigurieren.
  ```
</Card>

## 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:

<Card title="Example">
  ```text Parameters theme={null}
  tag_handling=xml, split_sentences=nonewlines
  ```

  ```markup Example request theme={null}
  <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>
  ```

  ```markup Example response theme={null}
  <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>
  ```
</Card>

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

<Card title="Incorrect translation due to new lines" horizontal="false">
  ```markup Request theme={null}
  <div>She bought oat
  biscuits.</div>
  ```

  ```markup Response theme={null}
  <div>Sie kaufte Hafer
  Kekse.</div>
  ```

  The two parts of the sentence have been translated separately: "oat biscuits" became "Hafer Kekse" instead of "Haferkekse".
</Card>

## 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:

<Tabs>
  <Tab title="Restricted Splitting">
    ```text Parameters theme={null}
    tag_handling=xml, non_splitting_tags=par
    ```

    ```markup Request theme={null}
    <par>The firm said it had been </par><par> conducting an internal investigation.</par>
    ```

    ```markup Response theme={null}
    <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).
  </Tab>

  <Tab title="Without non_splitting_tags">
    ```text Parameters theme={null}
    tag_handling=xml
    ```

    ```markup Request theme={null}
    <par>The firm said it had been </par><par> conducting an internal investigation.</par>
    ```

    ```markup Response theme={null}
    <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.
  </Tab>
</Tabs>

## 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:

<Card title="Outline detection example">
  ```text Parameters theme={null}
  tag_handling=xml, split_sentences=nonewlines, outline_detection=0, splitting_tags=par,title
  ```

  ```markup Example request theme={null}
  <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>
  ```

  ```markup Example response theme={null}
  <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>
  ```
</Card>

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