Document translations

​

Document File Size Limits

​

Billing minimums

​

One source/target language pair per upload

​

Same-language source and target are rejected

​

Format-specific gotchas

• Only text between element tags is translated. Attribute values and processing instructions are left alone.
• XML <!-- comments --> may be picked up as translatable text and their delimiters escaped in the output — strip comments before uploading if downstream tooling relies on them.
• CDATA section content is translated — the markers are stripped and the inner text is sent to the engine. Move code, regex, and other non-translatable content out of CDATA blocks first.
• translate="no" on any XML element excludes its content from translation.
• Files using ITS 2.0 external rules (its:rules/@xlink:href) currently return HTTP 500 — inline the rules or remove the reference.
• Malformed XML currently returns HTTP 500 instead of a 4xx. Validate with a standard XML parser before uploading.

• Only <source> content is translated; results are written to the corresponding <target>. Existing <target> values are overwritten — remove or split out already-translated units if you need to preserve them.
• The per-<file> source-language / target-language attributes are ignored — DeepL uses the API’s source_lang and target_lang for the entire upload.
• translate="no" on <trans-unit> (1.2) or <unit> (2.0) is fully honored.
• The state attribute is preserved as-is; if you use state="needs-translation", update it yourself after translation.
• An unsupported trgLang value on the root <xliff> element (e.g. arb-MOD) is rejected as “Invalid target language” even if the API target_lang is valid — remove or fix the attribute.

• Only DITA topic files (.dita) are supported. .ditamap uploads are rejected.
• translate="no" is fully honored on inline and block-level elements.
• Content references (conref, conkeyref) are not resolved — translate each referenced source topic independently.
• Newlines inside <codeblock>, <pre>, <msgblock>, and <screen> may be collapsed to single spaces. Move code samples out of the file before translation if line breaks matter.
• Topics with dense inline-element markup (combinations of <filepath>, <cmdname>, <option>, nested <indexterm>) may fail with an internal error — simplify or split the topic.

• Only string values are translated; keys, numbers, booleans, and null are not touched. Nested objects and arrays are traversed at every depth.
• Files must be strict, parseable JSON — no trailing commas, no comments. JSONC-style extensions are not supported.
• Upload limit is 1 MB regardless of plan. Large metadata payloads (e.g., DataCite, Zenodo, Backstage catalog dumps) may need to be split, or translated string-by-string via the text-translation API.
• Embedded HTML or Markdown inside string values (common in Contentful Rich Text and similar CMS payloads) is handled — DeepL translates the natural-language text and attempts to preserve the embedded markup. Review the output for complex rich-text content.
• Brace-delimited placeholders such as {stars} or {{userName}} are kept verbatim by default, so template variables survive translation. Multi-word groups such as {see note} are treated as translatable text. To translate placeholders along with the text, set input_conversion_options=version:1,json-placeholders:translate when uploading.
• ICU MessageFormat skeletons such as {count, plural, one {# item} other {# items}} are always protected: the variable name, keywords, and categories stay intact while the branch text is translated. Branch text is translated in isolation, so review plural forms in the output. Languages whose plural categories are absent from the source (for example Polish few/many from an English message) fall back to other. Expand categories in your i18n tooling if exact pluralization matters.
• To protect specific values from translation, encode them as non-strings (numbers/booleans/null) or pre-process the file to strip them.

• InDesign embeds font references, not the fonts themselves. If the target language uses characters not in the original font (e.g., Japanese in a Latin-only font), the output may show boxes or substituted glyphs — open the translated file in InDesign and swap fonts before distributing.
• Translated text is often longer than the source. Expect overset text (indicated by a red ”+” in InDesign) in fixed-size frames; review and resize after translation.
• IDML does not use translate="no". Protect content via InDesign character styles or by removing the affected text frames before exporting.

• The file must be genuine Adobe FrameMaker MIF. .mif files from other tools (e.g. Quartus memory-init files, MathML wrapped as MIF) currently return HTTP 500 rather than being rejected cleanly. Rename or convert them before uploading.
• MIF 8.00 and later are supported. Older MIF variants are best-effort — open and re-save from a recent FrameMaker version if the upload fails.
• Save as UTF-8 from FrameMaker before uploading; the file should begin with a <MIFFile ...> header.
• Some valid FrameMaker 10 MIF files may fail with HTTP 500 — try re-saving from a newer FrameMaker version.
• MIF does not use translate="no". Protect content via FrameMaker conditional text or character formatting.

• Cell text is translated across all sheets; rich text formatting, merged cells, and multi-sheet layouts are preserved. Numbers and dates are left unchanged.
• Macros are preserved byte-for-byte and never translated. The VBA project is carried through untouched, so user-facing strings inside macro code remain in the source language.
• Formulas are preserved verbatim and cached values are kept as-is.
• Lookup formulas (VLOOKUP, MATCH, INDEX) whose lookup key is a text literal typed into the formula keep that literal in the source language while the table they search is translated, so the lookup can stop matching and return #N/A after recalculation. Key lookups off a cell reference (e.g. =VLOOKUP(D1,...)) instead.
• Files with no translatable text are rejected with No translatable text can be extracted from the document. This does not mean the file is malformed.

• The .zip must be a valid SCORM package (SCORM 1.2 or SCORM 2004) with imsmanifest.xml at the root of the archive. AICC, xAPI (Tin Can), and cmi5 packages are not supported and are rejected.
• Course titles in imsmanifest.xml and lesson content in the package’s HTML files are translated. Manifest identifiers, file paths, and HTML markup are preserved exactly.
• Audio and video files (MP3, MP4, WAV, images) are preserved byte-for-byte. DeepL does not transcribe or translate media content.
• Zip the contents, not the folder. imsmanifest.xml must sit at the root of the archive, exactly one. An archive that starts with a folder (e.g. course/imsmanifest.xml) is rejected.
• The manifest must be under 4 MB. A larger imsmanifest.xml is rejected.
• Non-SCORM .zip uploads are rejected with 400 Invalid or missing file extension.

• Cue text is translated; cue timings, identifiers, settings lines, and WEBVTT headers are preserved so subtitles stay in sync with the original media.
• Inline styling tags (e.g. <c>, <v Speaker>, karaoke timestamps) are preserved. Review their placement, since translated text length differs from the source.
• Files with no translatable text are rejected.

• String values are translated at every level of nesting; keys, numbers, booleans, null values, comments, and indentation structure are preserved.
• Placeholders and escape sequences (\n, \t, etc.) are preserved.
• Files with no translatable text are rejected.
• Malformed YAML (inconsistent indentation, unquoted special characters) returns an error. Validate before uploading.

• Property values are translated; keys and separators are preserved. Comment lines (# or !) are not translated.
• Placeholders ({0}, %s, %d) are normally preserved. Verify them after translation before shipping.
• Escaped characters (\n, \t, \:) are preserved.
• Files with no translatable text are returned unchanged.

• String values are translated; keys and the "key" = "value"; structure are preserved.
• Format specifiers (%@, %d, positional specifiers like %1$@) are normally preserved. Verify them after translation before shipping.
• Escaped characters (\n, \", \\) are preserved.
• Files with no translatable text are returned unchanged.

• Paragraphs, headings, list items, blockquotes, table cell content, and image alt text are translated. URLs and link targets are not, only the link label text is.
• YAML front matter is not translated. Known issue: the --- delimiters that open and close the front matter block are currently dropped from the translated file, which can fuse the metadata into the first paragraph. Re-add the --- lines after download, or move the front matter out of the file before uploading.
• HTML blocks embedded in Markdown are processed via an HTML sub-filter. Results may vary for complex inline HTML.
• Markdown formatting (bold, italic, headings, lists) is preserved.
• Malformed Markdown is accepted and translated as-is (not validated for well-formedness).

• String values in <data> elements are translated; element names, IDs, and XML structure are preserved. Comments in <comment> elements are not translated.
• Placeholders ({0}, %s) are normally preserved. Verify them after translation before shipping.
• Files with no translatable text are returned unchanged.

• Body text, headings, table content, footnotes, endnotes, annotations, and document metadata are translated.
• Accept or reject all tracked changes before uploading. Deleted text that has not been formally removed may still be extracted and translated.
• Consecutive tabs may be dropped during translation. Review content that relies on tab-based alignment.
• If the target language requires characters outside the document’s fonts, they may not render correctly. Check fonts after translation.

• Body text in paragraphs, headings, list items, table cells, footnotes, and endnotes is translated. RTF control words, groups, and formatting tokens (\b, \i, \par, \fonttbl, etc.) are preserved untouched.
• Non-ASCII characters are written as \uXXXX? escape sequences. Old RTF readers that ignore \u escapes will show only the ASCII fallback character. Open the result in a modern reader (Word 2007+, LibreOffice).
• Embedded objects (images, OLE objects, embedded fonts) are preserved as binary blocks and not modified.
• Fields (\field) are preserved, but field instruction text is not translated. Only the displayed text result is.
• Hyperlink targets are not translated; only the link’s display text is.

​

Polling and translation time

​

Using glossaries with documents

​

Requesting a quality evaluation

• The language pair must be in the supported language pairs. Quality evaluation supports fewer language pairs than document translation.
• The file must be docx, pptx, pdf, idml, xml, dita, mif, or XLIFF 1.2/2.0/2.1. Quality evaluation supports fewer file types than document translation.
• Your account must have enough quality evaluation characters. Quality evaluation characters are metered separately from translation characters.

curl -X POST https://api.deepl.com/v2/document \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --form 'source_lang=EN' \
  --form 'target_lang=DE' \
  --form 'file=@quarterly-report.docx' \
  --form 'enable_quality_evaluation=true'

{
  "document_id": "04DE5AD98A02647D83285A36021911C6",
  "document_key": "0CB0054F1C132C1625B392EADDA41CB754A742822F6877173029A6C487E7F60A",
  "quality_evaluation_job_id": "04DE5AD98A02647D83285A36021911C6"
}

curl https://api.deepl.com/v1/quality-evaluations/04DE5AD98A02647D83285A36021911C6 \
  --header "Authorization: DeepL-Auth-Key $API_KEY"

{
  "job_id": "04DE5AD98A02647D83285A36021911C6",
  "status": "done",
  "segments": [
    {
      "segment_index": 0,
      "segment_score": 38.5,
      "source": "Our Q3 revenue came in 5% above forecast.",
      "target": "Unser Q3-Umsatz lag 5 % unter der Prognose.",
      "applied_glossary_term_pairs": [
        {
          "source_term": "forecast",
          "target_term": "Prognose",
          "ranges": [{ "start": 34, "end": 42 }]
        }
      ],
      "errors": [
        {
          "type": "Accuracy",
          "sub_type": "Mistranslation",
          "severity": "Critical",
          "explanation": "The source says revenue was '5% above forecast' but the translation says '5 % unter der Prognose' (5% below forecast). This reverses the meaning.",
          "source_spans": [{ "start": 23, "end": 31 }],
          "target_spans": [{ "start": 20, "end": 29 }]
        }
      ]
    }
  ]
}

​

Document format conversions

• Translating a .doc file returns a .docx file.
• With the output_format parameter on upload, you can translate a PDF and receive an editable Microsoft Word document (output_format=docx). No other input formats support alternative output formats.

​

Error 429: Too Many Requests

• You send concurrent document translation requests that exceed your account quota.
• You have too many un-retrieved or non-downloaded translated documents.

• Polling document translation status, taking into account its frequency in order to prevent excessive load
• Quicker time to document retrieval
• Retries with exponential backoff

​

Error 456: Quota Exceeded