From de37959b09ce36ce1f6d05f685ae4341bd389318 Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 7 Jul 2026 15:14:54 +0100 Subject: [PATCH 1/3] docs(document-translation): document Cat 1 file formats (IDML, XML, JSON, DITA, MIF) Add Cat 1 formats to all supported-format listings, update XLIFF version wording to include 1.2/2.0/2.1, bump Word/PowerPoint/PDF API Pro size cap to 100 MB, and add a Format-specific gotchas section to the document-translation best-practices page. Co-Authored-By: Claude Opus 4.7 --- api-reference/document.mdx | 14 ++++- api-reference/openapi.json | 4 +- api-reference/openapi.yaml | 14 ++++- docs/best-practices/document-translations.mdx | 59 ++++++++++++++++++- docs/getting-started/about.mdx | 2 +- .../cookbook/java-document-translator.mdx | 9 ++- docs/resources/usage-limits.mdx | 13 ++-- 7 files changed, 100 insertions(+), 15 deletions(-) diff --git a/api-reference/document.mdx b/api-reference/document.mdx index 70ac7586..f0767ac7 100644 --- a/api-reference/document.mdx +++ b/api-reference/document.mdx @@ -12,8 +12,13 @@ The document translation API allows you to translate whole documents and support * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document -* `xlf / xliff` - XLIFF Document, version 2.1 +* `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT (SubRip Subtitle) Document +* `idml` - Adobe InDesign Markup Language +* `xml` - XML Document +* `json` - JSON Document +* `dita` - DITA topic (Darwin Information Typing Architecture) +* `mif` - Adobe FrameMaker Interchange Format * `jpeg` / `jpg` / `png` - Image (currently in beta) Please note that with every submitted document of type .pptx, .docx, .doc, .xlsx, or .pdf, you are billed a minimum of 50,000 characters with the DeepL API plan, no matter how many characters are included in the document. @@ -137,8 +142,13 @@ These examples are for demonstration purposes only. In production code, the auth
  • `pdf`: Portable Document Format
  • `htm / .html`: HTML Document
  • `txt`: Plain Text Document
    • -
  • `xlf / xliff`: XLIFF Document, version 2.1
    • +
  • `xlf / xliff`: XLIFF Document (versions 1.2, 2.0, and 2.1)
  • `srt` - SRT (SubRip Subtitle) Document
    • +
  • `idml`: Adobe InDesign Markup Language
    • +
  • `xml`: XML Document
    • +
  • `json`: JSON Document
    • +
  • `dita`: DITA topic (Darwin Information Typing Architecture)
    • +
  • `mif`: Adobe FrameMaker Interchange Format
  • `jpeg` / `jpg` / `png` - Image (currently in beta)
    • diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 8cc0489b..32b0740d 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -35,7 +35,7 @@ }, { "name": "TranslateDocuments", - "description": "The document translation API allows you to translate whole documents and supports the following file types and extensions:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `xlsx` - Microsoft Excel Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n * `xlf / xliff` - XLIFF Document, version 2.1\n * `srt` - SRT Document\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" + "description": "The document translation API allows you to translate whole documents and supports the following file types and extensions:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `xlsx` - Microsoft Excel Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1)\n * `srt` - SRT Document\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" }, { "name": "RephraseText", @@ -1131,7 +1131,7 @@ "file": { "type": "string", "format": "binary", - "description": "The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `xlsx` - Microsoft Excel Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n * `xlf / xliff` - XLIFF Document, version 2.1\n * `srt` - SRT Document\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" + "description": "The document file to be translated. The file name should be included in this part's content disposition. As an alternative, the filename parameter can be used. The following file types and extensions are supported:\n * `docx` - Microsoft Word Document\n * `pptx` - Microsoft PowerPoint Document\n * `xlsx` - Microsoft Excel Document\n * `pdf` - Portable Document Format\n * `htm / html` - HTML Document\n * `txt` - Plain Text Document\n * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1)\n * `srt` - SRT Document\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" }, "filename": { "type": "string", diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 385f7995..a33ca7ee 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -33,8 +33,13 @@ tags: * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document - * `xlf / xliff` - XLIFF Document, version 2.1 + * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document + * `idml` - Adobe InDesign Markup Language + * `xml` - XML Document + * `json` - JSON Document + * `dita` - DITA topic (Darwin Information Typing Architecture) + * `mif` - Adobe FrameMaker Interchange Format * `jpeg` / `jpg` / `png` - Image (currently in beta) - name: RephraseText description: |- @@ -872,8 +877,13 @@ paths: * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document - * `xlf / xliff` - XLIFF Document, version 2.1 + * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document + * `idml` - Adobe InDesign Markup Language + * `xml` - XML Document + * `json` - JSON Document + * `dita` - DITA topic (Darwin Information Typing Architecture) + * `mif` - Adobe FrameMaker Interchange Format * `jpeg` / `jpg` / `png` - Image (currently in beta) filename: type: string diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 57db0ce3..6fd6898a 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -7,11 +7,66 @@ public: true Below you will find general guidance on how to handle status codes and error details to ensure a smooth document translation experience. ### Document File Size Limits -We impose [size limits](/docs/resources/usage-limits) per file type. -For `.pptx` and `.docx` types, our .NET, PHP and NodeJS client libraries offer functionality to minify files by temporarily extracting large media formats before sending them to the DeepL API. Stripped media are reinserted after document translation is completed. +We impose [size limits](/docs/resources/usage-limits) per file type. Limits vary by format — for example, `.docx` / `.pptx` / `.pdf` can be up to 100 MB on API Pro, `.idml` / `.mif` / `.xlsx` up to 30 MB, `.json` 1 MB, `.dita` 5 MB. +For `.pptx` and `.docx` types, our .NET, PHP and NodeJS client libraries offer functionality to minify files by temporarily extracting large media formats before sending them to the DeepL API. Stripped media are reinserted after document translation is completed. This allows users to translate files that might hit the size limit. +### One source/target language pair per upload +The `source_lang` and `target_lang` values on the request apply to the entire uploaded file. For most formats, keep each upload to a single source language for consistent results — behavior on content that isn't in the selected source language is not guaranteed. + +**XLIFF** is the exception: `` elements are translated as independent segments, so XLIFF files containing segments in different languages are handled segment-by-segment. Note: the per-`` `source-language` attribute inside an XLIFF is ignored — DeepL uses the request's `source_lang` value for every segment. + +All content in the uploaded file counts toward billed characters, including content that was not actually translated. + +### Same-language source and target are rejected +Requests where the source and target languages are equal — including regional variants of the same language, e.g. `EN` → `EN-US` or `EN-US` → `EN-GB` — are rejected with HTTP 400 (`Source and target language are equal.`). To adapt regional spelling, post-process the translated output yourself. + +### Format-specific gotchas + +Each supported format has behaviors and constraints worth knowing before you upload. The most common surprises: + +**XML** +- Only text between element tags is translated. Attribute values and processing instructions are left alone. +- XML `` 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. + +**XLIFF** +- Only `` content is translated; results are written to the corresponding ``. **Existing `` values are overwritten** — remove or split out already-translated units if you need to preserve them. +- The per-`` `source-language` / `target-language` attributes are ignored — DeepL uses the API's `source_lang` and `target_lang` for the entire upload. +- `translate="no"` on `` (1.2) or `` (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 `` element (e.g. `arb-MOD`) is rejected as "Invalid target language" even if the API `target_lang` is valid — remove or fix the attribute. + +**DITA** +- 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 ``, `
    `, ``, and `` 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 ``, ``, `