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

> ## Agent Instructions
> Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.
> Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).
> Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.
> Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid.

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