docs(document-translation): document Cat 1 file formats (IDML, XML, JSON, DITA, MIF)

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
     <li>`pdf`: Portable Document Format</li>
     <li>`htm / .html`: HTML Document</li>
     <li>`txt`: Plain Text Document</li>
-    <li>`xlf / xliff`: XLIFF Document, version 2.1</li>
+    <li>`xlf / xliff`: XLIFF Document (versions 1.2, 2.0, and 2.1)</li>
     <li>`srt` - SRT (SubRip Subtitle) Document</li>
+    <li>`idml`: Adobe InDesign Markup Language</li>
+    <li>`xml`: XML Document</li>
+    <li>`json`: JSON Document</li>
+    <li>`dita`: DITA topic (Darwin Information Typing Architecture)</li>
+    <li>`mif`: Adobe FrameMaker Interchange Format</li>
     <li>`jpeg` / `jpg` / `png` - Image (currently in beta)</li>
   </ul>
 </ParamField>

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",

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

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 and API plan.
+For DOCX and PPTX, 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: `<source>` elements are translated as independent segments, so XLIFF files containing segments in different languages are handled segment-by-segment. Note: the per-`<file>` `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 `<!-- 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.
+
+**XLIFF**
+- 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.
+
+**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 `<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.
+
+**JSON**
+- 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.
+- To protect specific values from translation, encode them as non-strings (numbers/booleans/null) or pre-process the file to strip them.
+
+**IDML**
+- 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.
+
+**MIF**
+- 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.
+
 ### Error 429: Too Many Requests
 This error may occur when: 
 

docs/getting-started/about.mdx

@@ -22,7 +22,7 @@ In addition, many leading computer-assisted translation (CAT) tool providers hav
 
 ## Why the DeepL API?
 
-- **High-quality text and document translations**: DeepL [consistently outperforms the competition](https://www.deepl.com/quality.html) in translation quality—and not only for text translation. The API also supports [.docx, .pptx, .xlsx, .txt, PDF, and HTML](/api-reference/document) files.
+- **High-quality text and document translations**: DeepL [consistently outperforms the competition](https://www.deepl.com/quality.html) in translation quality—and not only for text translation. The API also supports [many document, publishing, and localization formats](/api-reference/document) including DOCX, PPTX, XLSX, PDF, HTML, IDML, XLIFF, XML, JSON, DITA, and MIF.
 - **Maximum data security**: With DeepL API paid plans, texts aren’t saved on persistent storage and aren’t used to train our models. And DeepL adheres strictly to EU data protection laws and ISO 27001. [Learn more about data security at DeepL](https://www.deepl.com/pro-data-security/).
 - **Customization with glossaries**: [Specify your own translations for words and phrases](/api-reference/multilingual-glossaries), and customize your translations consistently and at scale.
 

docs/learning-how-tos/cookbook/java-document-translator.mdx

@@ -95,9 +95,14 @@ static {
     map.put("htm", "HTML Document");
     map.put("html", "HTML Document");
     map.put("txt", "Plain Text Document");
-    map.put("xlf", "XLIFF Document, version 2.1");
-    map.put("xliff", "XLIFF Document, version 2.1");
+    map.put("xlf", "XLIFF Document (1.2 / 2.0 / 2.1)");
+    map.put("xliff", "XLIFF Document (1.2 / 2.0 / 2.1)");
     map.put("srt", "SubRip Subtitle file");
+    map.put("idml", "Adobe InDesign Markup Language");
+    map.put("xml", "XML Document");
+    map.put("json", "JSON Document");
+    map.put("dita", "DITA topic");
+    map.put("mif", "Adobe FrameMaker Interchange Format");
     SUPPORTED_EXTENSIONS = Collections.unmodifiableMap(map);
 }
 ```

docs/resources/usage-limits.mdx

@@ -14,17 +14,22 @@ title: "Usage and limits"
 
 | File Format             | DeepL API Free                 | DeepL API Pro                    |
 | ----------------------- | ------------------------------ | -------------------------------- |
-| Word (.docx / .doc)     | 10 MB<br />500,000 characters  | 30 MB<br />1 million characters  |
-| PowerPoint (.pptx)      | 10 MB <br />500,000 characters | 30 MB<br />1 million characters  |
+| Word (.docx / .doc)     | 10 MB<br />500,000 characters  | 100 MB<br />1 million characters |
+| PowerPoint (.pptx)      | 10 MB <br />500,000 characters | 100 MB<br />1 million characters |
 | Excel (.xlsx)           | 10 MB <br />500,000 characters | 30 MB<br />1 million characters  |
-| PDF (.pdf)              | 10 MB <br />500,000 characters | 30 MB<br />1 million characters  |
+| PDF (.pdf)              | 10 MB <br />500,000 characters | 100 MB<br />1 million characters |
 | Text (.txt)             | 1 MB<br />500,000 characters   | 1 MB <br />1 million characters  |
 | HTML (.html)            | 5 MB<br />500,000 characters   | 5 MB<br />1 million characters   |
+| IDML (.idml)            | 10 MB<br />500,000 characters  | 30 MB<br />1 million characters  |
+| MIF (.mif)              | 10 MB<br />500,000 characters  | 30 MB<br />1 million characters  |
+| XML (.xml)              | 10 MB<br />500,000 characters  | 10 MB<br />1 million characters  |
+| JSON (.json)            | 1 MB<br />500,000 characters   | 1 MB<br />1 million characters   |
+| DITA (.dita)            | 5 MB<br />500,000 characters   | 5 MB<br />1 million characters   |
 | XLIFF (.xlf/.xliff)\*   | 10 MB<br />500,000 characters  | 10 MB<br />1 million characters  |
 | SRT (.srt)              | 150 KB<br />500,000 characters | 150 KB<br />1 million characters |
 | Images (.jpeg/.png)\*\* | 3 MB<br />500,000 characters   | 3 MB<br />1 million characters   |
 
-*Please note that DeepL only supports .xliff files with the version 2.1.<br />
+*DeepL supports XLIFF versions 1.2, 2.0, and 2.1 (2.1 shares the 2.0 core namespace).<br />
 **Image translation is currently in Beta. During the Beta phase, characters translated in image file formats are not billed and not counted against your character threshold.
 
 ### Your Usage