From 0fb8ae4b9904b137f3304199c5cfeab6db445238 Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 29 Sep 2026 17:04:50 +0100 Subject: [PATCH 1/9] Document new file formats and suppress-image-types conversion option - Add input_conversion_options parameter to POST /v2/document with suppress-image-types key (pptx only): hyphen-joined image content type list (e.g. logo-photo) or all, plus a SuppressImages request example - Add ten new file types to both file type lists: xlsm, zip (SCORM), vtt, yaml/yml, properties, strings, md/markdown, and beta resx/odt/rtf - Add format-specific gotchas for all ten formats to document translation best practices (SCORM manifest rules, XLSM lookup-formula pitfall, Markdown front matter issue, RTF unicode escapes, and more) - Extend billing minimums to xlsm and odt - Add per-format upload limits for the new formats to usage and limits - Update the About page format list - Add September 2026 changelog entry --- api-reference/openapi.yaml | 37 +++++++++++ docs/best-practices/document-translations.mdx | 65 ++++++++++++++++++- docs/getting-started/about.mdx | 2 +- docs/resources/roadmap-and-release-notes.mdx | 5 ++ docs/resources/usage-limits.mdx | 45 ++++++++----- 5 files changed, 135 insertions(+), 19 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index e54b344a..9c7d4f4b 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -30,16 +30,26 @@ tags: * `docx` - Microsoft Word Document * `pptx` - Microsoft PowerPoint Document * `xlsx` - Microsoft Excel Document + * `xlsm` - Microsoft Excel Macro-Enabled Workbook * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document + * `vtt` - WebVTT Subtitle Document * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document + * `yaml / yml` - YAML Document + * `properties` - Java Properties Document + * `strings` - iOS/macOS Strings Document + * `md / markdown` - Markdown Document * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format + * `zip` - SCORM Package (e-learning content) + * `odt` - OpenDocument Text Document (currently in beta) + * `rtf` - Rich Text Format Document (currently in beta) + * `resx` - .NET Resource Document (currently in beta) * `jpeg` / `jpg` / `png` - Image (currently in beta) - name: RephraseText description: |- @@ -884,6 +894,12 @@ paths: target_lang: DE file: '@document.pdf' enable_watermark: true + SuppressImages: + summary: Suppressing translation of embedded images (pptx only) + value: + target_lang: DE + file: '@document.pptx' + input_conversion_options: 'version:1,suppress-image-types:all' Glossary: summary: Using a Glossary value: @@ -938,16 +954,26 @@ paths: * `docx` - Microsoft Word Document * `pptx` - Microsoft PowerPoint Document * `xlsx` - Microsoft Excel Document + * `xlsm` - Microsoft Excel Macro-Enabled Workbook * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document + * `vtt` - WebVTT Subtitle Document * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document + * `yaml / yml` - YAML Document + * `properties` - Java Properties Document + * `strings` - iOS/macOS Strings Document + * `md / markdown` - Markdown Document * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format + * `zip` - SCORM Package (e-learning content) + * `odt` - OpenDocument Text Document (currently in beta) + * `rtf` - Rich Text Format Document (currently in beta) + * `resx` - .NET Resource Document (currently in beta) * `jpeg` / `jpg` / `png` - Image (currently in beta) filename: type: string @@ -957,6 +983,17 @@ paths: type: string description: | File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file. + input_conversion_options: + description: |- + Comma-separated list of `key:value` conversion options, prefixed with a version, that control how the input document is converted before translation. For example: `version:1,suppress-image-types:all`. + + Supported keys: + + * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`. + + Only `pptx` documents support conversion options; for other file types this parameter is ignored. Unrecognized keys are ignored. + type: string + example: version:1,suppress-image-types:all formality: $ref: '#/components/schemas/Formality' glossary_id: diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 7bf234bb..6266bdc8 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -15,7 +15,7 @@ For DOCX and PPTX, our .NET, PHP and NodeJS client libraries offer functionality This allows users to translate files that might hit the size limit. ### Billing minimums -Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, or `.pdf` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. +Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, `.xlsm`, `.pdf`, or `.odt` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. ### 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. @@ -72,6 +72,69 @@ Each supported format has behaviors and constraints worth knowing before you upl - 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. +**XLSM** +- 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. + +**SCORM (`.zip`)** +- 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`. + +**VTT (WebVTT)** +- 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. ``, ``, karaoke timestamps) are preserved. Review their placement, since translated text length differs from the source. +- Files with no translatable text are rejected. + +**YAML / YML** +- 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. + +**Java `.properties`** +- 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. + +**iOS/macOS `.strings`** +- 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. + +**Markdown (`.md` / `.markdown`)** +- 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). + +**RESX** (currently in beta) +- String values in `` elements are translated; element names, IDs, and XML structure are preserved. Comments in `` elements are not translated. +- Placeholders (`{0}`, `%s`) are normally preserved. Verify them after translation before shipping. +- Files with no translatable text are returned unchanged. + +**ODT** (currently in beta) +- 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. + +**RTF** (currently in beta) +- 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 Translation time depends on document size and server load: small documents typically finish in seconds, larger ones in 1-2 minutes once translation has started. Poll the [status endpoint](/api-reference/document/check-document-status) at regular intervals or with exponential backoff. Treat the `seconds_remaining` field as a rough estimate only; it can be unreliable and occasionally returns implausible values (e.g. 2^27). diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx index 4b622cc3..c18e7ac5 100644 --- a/docs/getting-started/about.mdx +++ b/docs/getting-started/about.mdx @@ -23,7 +23,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 [many document, publishing, and localization formats](/api-reference/document/upload-and-translate-a-document) including DOCX, PPTX, XLSX, PDF, HTML, IDML, XLIFF, XML, JSON, DITA, and MIF. +- **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/upload-and-translate-a-document) including DOCX, PPTX, XLSX, XLSM, PDF, HTML, IDML, XLIFF, XML, JSON, YAML, Markdown, DITA, MIF, SCORM, ODT, RTF, and more. - **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](/docs/customize/managing-glossaries), and customize your translations consistently and at scale. diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 06e6e9ca..2c7b0ce1 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -9,6 +9,11 @@ rss: true +## September 29 - New Document Formats and Embedded Image Translation Controls +- [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now supports ten additional file formats: `xlsm` (macro-enabled Excel), `zip` (SCORM e-learning packages), `vtt` (WebVTT subtitles), `yaml` / `yml`, `properties` (Java properties), `strings` (iOS/macOS strings), `md` / `markdown`, `resx` (.NET resources, currently in beta), `odt` (OpenDocument Text, currently in beta), and `rtf` (Rich Text Format, currently in beta). +- A new `input_conversion_options` parameter controls how the input document is converted before translation. The `suppress-image-types` option leaves specified types of images embedded in `pptx` documents untranslated. For example, `version:1,suppress-image-types:all` suppresses all embedded images, and `version:1,suppress-image-types:logo-photo` suppresses logos and photos only. +- See [document translation best practices](/docs/best-practices/document-translations) for format-specific guidance and known constraints. + ## September 29 - Style Rules for Language Variants - [Style rule lists](/docs/customize/using-style-rules) hold the configured rules and custom instructions DeepL applies when translating into one target language. A list could previously only be created for a root language such as `de`, and it applied to every variant of that language. You can now also create a list for a specific variant, such as `de-CH` or `en-GB`, so conventions that differ between variants stay separate. - Set the variant code in the `language` field of [`POST /v3/style_rules`](/api-reference/style-rules/create-style-rule). A variant list applies when `target_lang` is that variant; root-language lists keep applying to all variants as before. diff --git a/docs/resources/usage-limits.mdx b/docs/resources/usage-limits.mdx index b6159d64..9a836768 100644 --- a/docs/resources/usage-limits.mdx +++ b/docs/resources/usage-limits.mdx @@ -12,25 +12,36 @@ description: "Request size, header, and character limits for the DeepL API, plus ### Maximum Upload Limits Per Document Format -| File Format | DeepL API - free plans | DeepL API - paid plans | -| ----------------------- | ------------------------------ | -------------------------------- | -| Word (.docx / .doc) | 10 MB
500,000 characters | 100 MB
1 million characters | -| PowerPoint (.pptx) | 10 MB
500,000 characters | 100 MB
1 million characters | -| Excel (.xlsx) | 10 MB
500,000 characters | 30 MB
1 million characters | -| PDF (.pdf) | 10 MB
500,000 characters | 100 MB
1 million characters | -| Text (.txt) | 1 MB
500,000 characters | 1 MB
1 million characters | -| HTML (.html) | 5 MB
500,000 characters | 5 MB
1 million characters | -| IDML (.idml) | 10 MB
500,000 characters | 30 MB
1 million characters | -| MIF (.mif) | 10 MB
500,000 characters | 30 MB
1 million characters | -| XML (.xml) | 10 MB
500,000 characters | 10 MB
1 million characters | -| JSON (.json) | 1 MB
500,000 characters | 1 MB
1 million characters | -| DITA (.dita) | 5 MB
500,000 characters | 5 MB
1 million characters | -| XLIFF (.xlf/.xliff)\* | 10 MB
500,000 characters | 10 MB
1 million characters | -| SRT (.srt) | 150 KB
500,000 characters | 150 KB
1 million characters | -| Images (.jpeg/.png)\*\* | 3 MB
500,000 characters | 3 MB
1 million characters | +| File Format | DeepL API - free plans | DeepL API - paid plans | +| ---------------------------- | ------------------------------ | -------------------------------- | +| Word (.docx / .doc) | 10 MB
500,000 characters | 100 MB
1 million characters | +| PowerPoint (.pptx) | 10 MB
500,000 characters | 100 MB
1 million characters | +| Excel (.xlsx) | 10 MB
500,000 characters | 30 MB
1 million characters | +| Excel Macro-Enabled (.xlsm) | 10 MB
500,000 characters | 30 MB
1 million characters | +| PDF (.pdf) | 10 MB
500,000 characters | 100 MB
1 million characters | +| Text (.txt) | 1 MB
500,000 characters | 1 MB
1 million characters | +| HTML (.html) | 5 MB
500,000 characters | 5 MB
1 million characters | +| IDML (.idml) | 10 MB
500,000 characters | 30 MB
1 million characters | +| MIF (.mif) | 10 MB
500,000 characters | 30 MB
1 million characters | +| XML (.xml) | 10 MB
500,000 characters | 10 MB
1 million characters | +| JSON (.json) | 1 MB
500,000 characters | 1 MB
1 million characters | +| YAML (.yaml / .yml) | 1 MB
500,000 characters | 1 MB
1 million characters | +| Java Properties (.properties)| 1 MB
500,000 characters | 1 MB
1 million characters | +| iOS/macOS Strings (.strings) | 1 MB
500,000 characters | 1 MB
1 million characters | +| Markdown (.md / .markdown) | 5 MB
500,000 characters | 5 MB
1 million characters | +| DITA (.dita) | 5 MB
500,000 characters | 5 MB
1 million characters | +| XLIFF (.xlf/.xliff)\* | 10 MB
500,000 characters | 10 MB
1 million characters | +| SRT (.srt) | 150 KB
500,000 characters | 150 KB
1 million characters | +| WebVTT (.vtt) | 150 KB
500,000 characters | 150 KB
1 million characters | +| SCORM (.zip) | 10 MB
500,000 characters | 100 MB
1 million characters | +| RESX (.resx)\*\*\* | 10 MB
500,000 characters | 10 MB
1 million characters | +| ODT (.odt)\*\*\* | 10 MB
500,000 characters | 100 MB
1 million characters | +| RTF (.rtf)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | +| Images (.jpeg/.png)\*\* | 3 MB
500,000 characters | 3 MB
1 million characters | *DeepL supports XLIFF versions 1.2, 2.0, and 2.1 (2.1 shares the 2.0 core namespace).
-**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. +**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.
+***Currently in Beta. During the Beta phase, characters translated in these file formats are not billed and not counted against your character threshold. ### Your Usage From 5f966d1dfa1ca5fee7c38dd9a1894ca465aa064e Mon Sep 17 00:00:00 2001 From: yoshiamakino <300935191+yoshiamakino@users.noreply.github.com> Date: Tue, 29 Sep 2026 16:05:13 +0000 Subject: [PATCH 2/9] chore: update OpenAPI JSON files from YAML sources --- api-reference/openapi.json | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index c2491d4d..31efdd9a 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 (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)" + "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 * `xlsm` - Microsoft Excel Macro-Enabled Workbook\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 * `vtt` - WebVTT Subtitle Document\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `yaml / yml` - YAML Document\n * `properties` - Java Properties Document\n * `strings` - iOS/macOS Strings Document\n * `md / markdown` - Markdown Document\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `zip` - SCORM Package (e-learning content)\n * `odt` - OpenDocument Text Document (currently in beta)\n * `rtf` - Rich Text Format Document (currently in beta)\n * `resx` - .NET Resource Document (currently in beta)\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" }, { "name": "RephraseText", @@ -1109,6 +1109,14 @@ "enable_watermark": true } }, + "SuppressImages": { + "summary": "Suppressing translation of embedded images (pptx only)", + "value": { + "target_lang": "DE", + "file": "@document.pptx", + "input_conversion_options": "version:1,suppress-image-types:all" + } + }, "Glossary": { "summary": "Using a Glossary", "value": { @@ -1172,7 +1180,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 (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)" + "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 * `xlsm` - Microsoft Excel Macro-Enabled Workbook\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 * `vtt` - WebVTT Subtitle Document\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `yaml / yml` - YAML Document\n * `properties` - Java Properties Document\n * `strings` - iOS/macOS Strings Document\n * `md / markdown` - Markdown Document\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `zip` - SCORM Package (e-learning content)\n * `odt` - OpenDocument Text Document (currently in beta)\n * `rtf` - Rich Text Format Document (currently in beta)\n * `resx` - .NET Resource Document (currently in beta)\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" }, "filename": { "type": "string", @@ -1182,6 +1190,11 @@ "type": "string", "description": "File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file.\n" }, + "input_conversion_options": { + "description": "Comma-separated list of `key:value` conversion options, prefixed with a version, that control how the input document is converted before translation. For example: `version:1,suppress-image-types:all`.\n\nSupported keys:\n\n * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`.\n\nOnly `pptx` documents support conversion options; for other file types this parameter is ignored. Unrecognized keys are ignored.", + "type": "string", + "example": "version:1,suppress-image-types:all" + }, "formality": { "$ref": "#/components/schemas/Formality" }, From 2429f72a8d4a667ffa99eaedc61d7081d5346b42 Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 29 Sep 2026 17:16:11 +0100 Subject: [PATCH 3/9] Mark all ten new file formats as beta xlsm, zip (SCORM), vtt, yaml/yml, properties, strings, md/markdown, resx, odt, and rtf are all in beta, not just resx/odt/rtf. Adds the beta marker to both file type lists, the format gotcha headings, the usage-limits table (single shared beta footnote), the changelog entry, and the About page format list. --- api-reference/openapi.yaml | 28 +++++----- docs/best-practices/document-translations.mdx | 14 ++--- docs/getting-started/about.mdx | 2 +- docs/resources/roadmap-and-release-notes.mdx | 4 +- docs/resources/usage-limits.mdx | 54 +++++++++---------- 5 files changed, 51 insertions(+), 51 deletions(-) diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 9c7d4f4b..de409c1b 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -30,23 +30,23 @@ tags: * `docx` - Microsoft Word Document * `pptx` - Microsoft PowerPoint Document * `xlsx` - Microsoft Excel Document - * `xlsm` - Microsoft Excel Macro-Enabled Workbook + * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta) * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document - * `vtt` - WebVTT Subtitle Document + * `vtt` - WebVTT Subtitle Document (currently in beta) * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document - * `yaml / yml` - YAML Document - * `properties` - Java Properties Document - * `strings` - iOS/macOS Strings Document - * `md / markdown` - Markdown Document + * `yaml / yml` - YAML Document (currently in beta) + * `properties` - Java Properties Document (currently in beta) + * `strings` - iOS/macOS Strings Document (currently in beta) + * `md / markdown` - Markdown Document (currently in beta) * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format - * `zip` - SCORM Package (e-learning content) + * `zip` - SCORM Package (e-learning content, currently in beta) * `odt` - OpenDocument Text Document (currently in beta) * `rtf` - Rich Text Format Document (currently in beta) * `resx` - .NET Resource Document (currently in beta) @@ -954,23 +954,23 @@ paths: * `docx` - Microsoft Word Document * `pptx` - Microsoft PowerPoint Document * `xlsx` - Microsoft Excel Document - * `xlsm` - Microsoft Excel Macro-Enabled Workbook + * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta) * `pdf` - Portable Document Format * `htm / html` - HTML Document * `txt` - Plain Text Document * `xlf / xliff` - XLIFF Document (versions 1.2, 2.0, and 2.1) * `srt` - SRT Document - * `vtt` - WebVTT Subtitle Document + * `vtt` - WebVTT Subtitle Document (currently in beta) * `idml` - Adobe InDesign Markup Language * `xml` - XML Document * `json` - JSON Document - * `yaml / yml` - YAML Document - * `properties` - Java Properties Document - * `strings` - iOS/macOS Strings Document - * `md / markdown` - Markdown Document + * `yaml / yml` - YAML Document (currently in beta) + * `properties` - Java Properties Document (currently in beta) + * `strings` - iOS/macOS Strings Document (currently in beta) + * `md / markdown` - Markdown Document (currently in beta) * `dita` - DITA topic (Darwin Information Typing Architecture) * `mif` - Adobe FrameMaker Interchange Format - * `zip` - SCORM Package (e-learning content) + * `zip` - SCORM Package (e-learning content, currently in beta) * `odt` - OpenDocument Text Document (currently in beta) * `rtf` - Rich Text Format Document (currently in beta) * `resx` - .NET Resource Document (currently in beta) diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 6266bdc8..22e75ec6 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -72,14 +72,14 @@ Each supported format has behaviors and constraints worth knowing before you upl - 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. -**XLSM** +**XLSM** (currently in beta) - 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. -**SCORM (`.zip`)** +**SCORM (`.zip`)** (currently in beta) - 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. @@ -87,30 +87,30 @@ Each supported format has behaviors and constraints worth knowing before you upl - 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`. -**VTT (WebVTT)** +**VTT (WebVTT)** (currently in beta) - 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. ``, ``, karaoke timestamps) are preserved. Review their placement, since translated text length differs from the source. - Files with no translatable text are rejected. -**YAML / YML** +**YAML / YML** (currently in beta) - 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. -**Java `.properties`** +**Java `.properties`** (currently in beta) - 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. -**iOS/macOS `.strings`** +**iOS/macOS `.strings`** (currently in beta) - 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. -**Markdown (`.md` / `.markdown`)** +**Markdown (`.md` / `.markdown`)** (currently in beta) - 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. diff --git a/docs/getting-started/about.mdx b/docs/getting-started/about.mdx index c18e7ac5..3cb9ac46 100644 --- a/docs/getting-started/about.mdx +++ b/docs/getting-started/about.mdx @@ -23,7 +23,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 [many document, publishing, and localization formats](/api-reference/document/upload-and-translate-a-document) including DOCX, PPTX, XLSX, XLSM, PDF, HTML, IDML, XLIFF, XML, JSON, YAML, Markdown, DITA, MIF, SCORM, ODT, RTF, and more. +- **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/upload-and-translate-a-document) including DOCX, PPTX, XLSX, PDF, HTML, IDML, XLIFF, XML, JSON, DITA, and MIF, plus beta support for XLSM, SCORM, WebVTT, YAML, Markdown, RESX, ODT, RTF, and more. - **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](/docs/customize/managing-glossaries), and customize your translations consistently and at scale. diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 2c7b0ce1..6659b8ad 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -9,8 +9,8 @@ rss: true -## September 29 - New Document Formats and Embedded Image Translation Controls -- [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now supports ten additional file formats: `xlsm` (macro-enabled Excel), `zip` (SCORM e-learning packages), `vtt` (WebVTT subtitles), `yaml` / `yml`, `properties` (Java properties), `strings` (iOS/macOS strings), `md` / `markdown`, `resx` (.NET resources, currently in beta), `odt` (OpenDocument Text, currently in beta), and `rtf` (Rich Text Format, currently in beta). +## September 29 - New Document Formats (Beta) and Embedded Image Translation Controls +- [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now supports ten additional file formats, all currently in beta: `xlsm` (macro-enabled Excel), `zip` (SCORM e-learning packages), `vtt` (WebVTT subtitles), `yaml` / `yml`, `properties` (Java properties), `strings` (iOS/macOS strings), `md` / `markdown`, `resx` (.NET resources), `odt` (OpenDocument Text), and `rtf` (Rich Text Format). - A new `input_conversion_options` parameter controls how the input document is converted before translation. The `suppress-image-types` option leaves specified types of images embedded in `pptx` documents untranslated. For example, `version:1,suppress-image-types:all` suppresses all embedded images, and `version:1,suppress-image-types:logo-photo` suppresses logos and photos only. - See [document translation best practices](/docs/best-practices/document-translations) for format-specific guidance and known constraints. diff --git a/docs/resources/usage-limits.mdx b/docs/resources/usage-limits.mdx index 9a836768..09192c57 100644 --- a/docs/resources/usage-limits.mdx +++ b/docs/resources/usage-limits.mdx @@ -12,36 +12,36 @@ description: "Request size, header, and character limits for the DeepL API, plus ### Maximum Upload Limits Per Document Format -| File Format | DeepL API - free plans | DeepL API - paid plans | -| ---------------------------- | ------------------------------ | -------------------------------- | -| Word (.docx / .doc) | 10 MB
500,000 characters | 100 MB
1 million characters | -| PowerPoint (.pptx) | 10 MB
500,000 characters | 100 MB
1 million characters | -| Excel (.xlsx) | 10 MB
500,000 characters | 30 MB
1 million characters | -| Excel Macro-Enabled (.xlsm) | 10 MB
500,000 characters | 30 MB
1 million characters | -| PDF (.pdf) | 10 MB
500,000 characters | 100 MB
1 million characters | -| Text (.txt) | 1 MB
500,000 characters | 1 MB
1 million characters | -| HTML (.html) | 5 MB
500,000 characters | 5 MB
1 million characters | -| IDML (.idml) | 10 MB
500,000 characters | 30 MB
1 million characters | -| MIF (.mif) | 10 MB
500,000 characters | 30 MB
1 million characters | -| XML (.xml) | 10 MB
500,000 characters | 10 MB
1 million characters | -| JSON (.json) | 1 MB
500,000 characters | 1 MB
1 million characters | -| YAML (.yaml / .yml) | 1 MB
500,000 characters | 1 MB
1 million characters | -| Java Properties (.properties)| 1 MB
500,000 characters | 1 MB
1 million characters | -| iOS/macOS Strings (.strings) | 1 MB
500,000 characters | 1 MB
1 million characters | -| Markdown (.md / .markdown) | 5 MB
500,000 characters | 5 MB
1 million characters | -| DITA (.dita) | 5 MB
500,000 characters | 5 MB
1 million characters | -| XLIFF (.xlf/.xliff)\* | 10 MB
500,000 characters | 10 MB
1 million characters | -| SRT (.srt) | 150 KB
500,000 characters | 150 KB
1 million characters | -| WebVTT (.vtt) | 150 KB
500,000 characters | 150 KB
1 million characters | -| SCORM (.zip) | 10 MB
500,000 characters | 100 MB
1 million characters | -| RESX (.resx)\*\*\* | 10 MB
500,000 characters | 10 MB
1 million characters | -| ODT (.odt)\*\*\* | 10 MB
500,000 characters | 100 MB
1 million characters | -| RTF (.rtf)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | -| Images (.jpeg/.png)\*\* | 3 MB
500,000 characters | 3 MB
1 million characters | +| File Format | DeepL API - free plans | DeepL API - paid plans | +| ---------------------------------- | ------------------------------ | -------------------------------- | +| Word (.docx / .doc) | 10 MB
500,000 characters | 100 MB
1 million characters | +| PowerPoint (.pptx) | 10 MB
500,000 characters | 100 MB
1 million characters | +| Excel (.xlsx) | 10 MB
500,000 characters | 30 MB
1 million characters | +| Excel Macro-Enabled (.xlsm)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | +| PDF (.pdf) | 10 MB
500,000 characters | 100 MB
1 million characters | +| Text (.txt) | 1 MB
500,000 characters | 1 MB
1 million characters | +| HTML (.html) | 5 MB
500,000 characters | 5 MB
1 million characters | +| IDML (.idml) | 10 MB
500,000 characters | 30 MB
1 million characters | +| MIF (.mif) | 10 MB
500,000 characters | 30 MB
1 million characters | +| XML (.xml) | 10 MB
500,000 characters | 10 MB
1 million characters | +| JSON (.json) | 1 MB
500,000 characters | 1 MB
1 million characters | +| YAML (.yaml / .yml)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | +| Java Properties (.properties)\*\*\*| 1 MB
500,000 characters | 1 MB
1 million characters | +| iOS/macOS Strings (.strings)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | +| Markdown (.md / .markdown)\*\*\* | 5 MB
500,000 characters | 5 MB
1 million characters | +| DITA (.dita) | 5 MB
500,000 characters | 5 MB
1 million characters | +| XLIFF (.xlf/.xliff)\* | 10 MB
500,000 characters | 10 MB
1 million characters | +| SRT (.srt) | 150 KB
500,000 characters | 150 KB
1 million characters | +| WebVTT (.vtt)\*\*\* | 150 KB
500,000 characters | 150 KB
1 million characters | +| SCORM (.zip)\*\*\* | 10 MB
500,000 characters | 100 MB
1 million characters | +| RESX (.resx)\*\*\* | 10 MB
500,000 characters | 10 MB
1 million characters | +| ODT (.odt)\*\*\* | 10 MB
500,000 characters | 100 MB
1 million characters | +| RTF (.rtf)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | +| Images (.jpeg/.png)\*\* | 3 MB
500,000 characters | 3 MB
1 million characters | *DeepL supports XLIFF versions 1.2, 2.0, and 2.1 (2.1 shares the 2.0 core namespace).
**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.
-***Currently in Beta. During the Beta phase, characters translated in these file formats are not billed and not counted against your character threshold. +***Currently in Beta. ### Your Usage From b92a091d6e1b58bb5ae494f7bf7ee580af37a36b Mon Sep 17 00:00:00 2001 From: yoshiamakino <300935191+yoshiamakino@users.noreply.github.com> Date: Tue, 29 Sep 2026 16:16:29 +0000 Subject: [PATCH 4/9] chore: update OpenAPI JSON files from YAML sources --- api-reference/openapi.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 31efdd9a..539f2c13 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 * `xlsm` - Microsoft Excel Macro-Enabled Workbook\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 * `vtt` - WebVTT Subtitle Document\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `yaml / yml` - YAML Document\n * `properties` - Java Properties Document\n * `strings` - iOS/macOS Strings Document\n * `md / markdown` - Markdown Document\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `zip` - SCORM Package (e-learning content)\n * `odt` - OpenDocument Text Document (currently in beta)\n * `rtf` - Rich Text Format Document (currently in beta)\n * `resx` - .NET Resource Document (currently in beta)\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 * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta)\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 * `vtt` - WebVTT Subtitle Document (currently in beta)\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `yaml / yml` - YAML Document (currently in beta)\n * `properties` - Java Properties Document (currently in beta)\n * `strings` - iOS/macOS Strings Document (currently in beta)\n * `md / markdown` - Markdown Document (currently in beta)\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `zip` - SCORM Package (e-learning content, currently in beta)\n * `odt` - OpenDocument Text Document (currently in beta)\n * `rtf` - Rich Text Format Document (currently in beta)\n * `resx` - .NET Resource Document (currently in beta)\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" }, { "name": "RephraseText", @@ -1180,7 +1180,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 * `xlsm` - Microsoft Excel Macro-Enabled Workbook\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 * `vtt` - WebVTT Subtitle Document\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `yaml / yml` - YAML Document\n * `properties` - Java Properties Document\n * `strings` - iOS/macOS Strings Document\n * `md / markdown` - Markdown Document\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `zip` - SCORM Package (e-learning content)\n * `odt` - OpenDocument Text Document (currently in beta)\n * `rtf` - Rich Text Format Document (currently in beta)\n * `resx` - .NET Resource Document (currently in beta)\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 * `xlsm` - Microsoft Excel Macro-Enabled Workbook (currently in beta)\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 * `vtt` - WebVTT Subtitle Document (currently in beta)\n * `idml` - Adobe InDesign Markup Language\n * `xml` - XML Document\n * `json` - JSON Document\n * `yaml / yml` - YAML Document (currently in beta)\n * `properties` - Java Properties Document (currently in beta)\n * `strings` - iOS/macOS Strings Document (currently in beta)\n * `md / markdown` - Markdown Document (currently in beta)\n * `dita` - DITA topic (Darwin Information Typing Architecture)\n * `mif` - Adobe FrameMaker Interchange Format\n * `zip` - SCORM Package (e-learning content, currently in beta)\n * `odt` - OpenDocument Text Document (currently in beta)\n * `rtf` - Rich Text Format Document (currently in beta)\n * `resx` - .NET Resource Document (currently in beta)\n * `jpeg` / `jpg` / `png` - Image (currently in beta)" }, "filename": { "type": "string", From c0e112533385184fef2b7fb5cf232283a4ec93cb Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 29 Sep 2026 17:17:58 +0100 Subject: [PATCH 5/9] Correct upload limits for new formats to match the format roadmap Markdown and RESX are 1 MB (not 5/10 MB), ODT is 30 MB on API Pro (not 100 MB), and SCORM is 10 MB on API Pro (not 100 MB). All other rows verified against the per-plan limits table. --- docs/resources/usage-limits.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/resources/usage-limits.mdx b/docs/resources/usage-limits.mdx index 09192c57..2f516f07 100644 --- a/docs/resources/usage-limits.mdx +++ b/docs/resources/usage-limits.mdx @@ -28,14 +28,14 @@ description: "Request size, header, and character limits for the DeepL API, plus | YAML (.yaml / .yml)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | | Java Properties (.properties)\*\*\*| 1 MB
500,000 characters | 1 MB
1 million characters | | iOS/macOS Strings (.strings)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | -| Markdown (.md / .markdown)\*\*\* | 5 MB
500,000 characters | 5 MB
1 million characters | +| Markdown (.md / .markdown)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | | DITA (.dita) | 5 MB
500,000 characters | 5 MB
1 million characters | | XLIFF (.xlf/.xliff)\* | 10 MB
500,000 characters | 10 MB
1 million characters | | SRT (.srt) | 150 KB
500,000 characters | 150 KB
1 million characters | | WebVTT (.vtt)\*\*\* | 150 KB
500,000 characters | 150 KB
1 million characters | -| SCORM (.zip)\*\*\* | 10 MB
500,000 characters | 100 MB
1 million characters | -| RESX (.resx)\*\*\* | 10 MB
500,000 characters | 10 MB
1 million characters | -| ODT (.odt)\*\*\* | 10 MB
500,000 characters | 100 MB
1 million characters | +| SCORM (.zip)\*\*\* | 10 MB
500,000 characters | 10 MB
1 million characters | +| RESX (.resx)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | +| ODT (.odt)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | | RTF (.rtf)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | | Images (.jpeg/.png)\*\* | 3 MB
500,000 characters | 3 MB
1 million characters | From 75a79acf301509c1f6e03e2955075ce93054df51 Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 29 Sep 2026 17:35:54 +0100 Subject: [PATCH 6/9] Restore billing explanation in the beta footnote The *** footnote for the beta file formats was a bare 'Currently in Beta.' stub. Restore the full sentence so it matches the ** image footnote: beta characters are not billed and not counted against the character threshold. --- docs/resources/usage-limits.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/usage-limits.mdx b/docs/resources/usage-limits.mdx index 2f516f07..84ed5dc7 100644 --- a/docs/resources/usage-limits.mdx +++ b/docs/resources/usage-limits.mdx @@ -41,7 +41,7 @@ description: "Request size, header, and character limits for the DeepL API, plus *DeepL supports XLIFF versions 1.2, 2.0, and 2.1 (2.1 shares the 2.0 core namespace).
**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.
-***Currently in Beta. +***Currently in Beta. During the Beta phase, characters translated in these file formats are not billed and not counted against your character threshold. ### Your Usage From 3492d4cd8bf914d9dbce3dadc65d4907a5e96b4d Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 29 Sep 2026 17:37:28 +0100 Subject: [PATCH 7/9] Use a single beta footnote for all beta formats Merge the image-specific ** footnote and the *** footnote into one generic ** footnote shared by images and the ten new beta formats. --- docs/resources/usage-limits.mdx | 55 ++++++++++++++++----------------- 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/docs/resources/usage-limits.mdx b/docs/resources/usage-limits.mdx index 84ed5dc7..de064c38 100644 --- a/docs/resources/usage-limits.mdx +++ b/docs/resources/usage-limits.mdx @@ -12,36 +12,35 @@ description: "Request size, header, and character limits for the DeepL API, plus ### Maximum Upload Limits Per Document Format -| File Format | DeepL API - free plans | DeepL API - paid plans | -| ---------------------------------- | ------------------------------ | -------------------------------- | -| Word (.docx / .doc) | 10 MB
500,000 characters | 100 MB
1 million characters | -| PowerPoint (.pptx) | 10 MB
500,000 characters | 100 MB
1 million characters | -| Excel (.xlsx) | 10 MB
500,000 characters | 30 MB
1 million characters | -| Excel Macro-Enabled (.xlsm)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | -| PDF (.pdf) | 10 MB
500,000 characters | 100 MB
1 million characters | -| Text (.txt) | 1 MB
500,000 characters | 1 MB
1 million characters | -| HTML (.html) | 5 MB
500,000 characters | 5 MB
1 million characters | -| IDML (.idml) | 10 MB
500,000 characters | 30 MB
1 million characters | -| MIF (.mif) | 10 MB
500,000 characters | 30 MB
1 million characters | -| XML (.xml) | 10 MB
500,000 characters | 10 MB
1 million characters | -| JSON (.json) | 1 MB
500,000 characters | 1 MB
1 million characters | -| YAML (.yaml / .yml)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | -| Java Properties (.properties)\*\*\*| 1 MB
500,000 characters | 1 MB
1 million characters | -| iOS/macOS Strings (.strings)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | -| Markdown (.md / .markdown)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | -| DITA (.dita) | 5 MB
500,000 characters | 5 MB
1 million characters | -| XLIFF (.xlf/.xliff)\* | 10 MB
500,000 characters | 10 MB
1 million characters | -| SRT (.srt) | 150 KB
500,000 characters | 150 KB
1 million characters | -| WebVTT (.vtt)\*\*\* | 150 KB
500,000 characters | 150 KB
1 million characters | -| SCORM (.zip)\*\*\* | 10 MB
500,000 characters | 10 MB
1 million characters | -| RESX (.resx)\*\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | -| ODT (.odt)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | -| RTF (.rtf)\*\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | -| Images (.jpeg/.png)\*\* | 3 MB
500,000 characters | 3 MB
1 million characters | +| File Format | DeepL API - free plans | DeepL API - paid plans | +| --------------------------------| ------------------------------ | -------------------------------- | +| Word (.docx / .doc) | 10 MB
500,000 characters | 100 MB
1 million characters | +| PowerPoint (.pptx) | 10 MB
500,000 characters | 100 MB
1 million characters | +| Excel (.xlsx) | 10 MB
500,000 characters | 30 MB
1 million characters | +| Excel Macro-Enabled (.xlsm)\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | +| PDF (.pdf) | 10 MB
500,000 characters | 100 MB
1 million characters | +| Text (.txt) | 1 MB
500,000 characters | 1 MB
1 million characters | +| HTML (.html) | 5 MB
500,000 characters | 5 MB
1 million characters | +| IDML (.idml) | 10 MB
500,000 characters | 30 MB
1 million characters | +| MIF (.mif) | 10 MB
500,000 characters | 30 MB
1 million characters | +| XML (.xml) | 10 MB
500,000 characters | 10 MB
1 million characters | +| JSON (.json) | 1 MB
500,000 characters | 1 MB
1 million characters | +| YAML (.yaml / .yml)\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | +| Java Properties (.properties)\*\*| 1 MB
500,000 characters | 1 MB
1 million characters | +| iOS/macOS Strings (.strings)\*\*| 1 MB
500,000 characters | 1 MB
1 million characters | +| Markdown (.md / .markdown)\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | +| DITA (.dita) | 5 MB
500,000 characters | 5 MB
1 million characters | +| XLIFF (.xlf/.xliff)\* | 10 MB
500,000 characters | 10 MB
1 million characters | +| SRT (.srt) | 150 KB
500,000 characters | 150 KB
1 million characters | +| WebVTT (.vtt)\*\* | 150 KB
500,000 characters | 150 KB
1 million characters | +| SCORM (.zip)\*\* | 10 MB
500,000 characters | 10 MB
1 million characters | +| RESX (.resx)\*\* | 1 MB
500,000 characters | 1 MB
1 million characters | +| ODT (.odt)\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | +| RTF (.rtf)\*\* | 10 MB
500,000 characters | 30 MB
1 million characters | +| Images (.jpeg/.png)\*\* | 3 MB
500,000 characters | 3 MB
1 million characters | *DeepL supports XLIFF versions 1.2, 2.0, and 2.1 (2.1 shares the 2.0 core namespace).
-**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.
-***Currently in Beta. During the Beta phase, characters translated in these file formats are not billed and not counted against your character threshold. +**Currently in Beta. During the Beta phase, characters translated in these file formats are not billed and not counted against your character threshold. ### Your Usage From 4053b38ef7e94f9526e3432900f8c7a024203aca Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 29 Sep 2026 17:39:00 +0100 Subject: [PATCH 8/9] Revert billing minimums to pre-beta format list .xlsm and .odt are in beta and beta characters are not billed, so the 50,000-character billing minimum does not apply to them yet. --- docs/best-practices/document-translations.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 22e75ec6..049186ae 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -15,7 +15,7 @@ For DOCX and PPTX, our .NET, PHP and NodeJS client libraries offer functionality This allows users to translate files that might hit the size limit. ### Billing minimums -Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, `.xlsm`, `.pdf`, or `.odt` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. +Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, or `.pdf` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. ### 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. From 4fd633282f08aeacc12a445b0c57d4a8367fa1d2 Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Tue, 29 Sep 2026 17:40:29 +0100 Subject: [PATCH 9/9] Note that beta formats are not subject to the billing minimum The 50,000-character minimum applies to the billed document formats (.pptx, .docx, .doc, .xlsx, .pdf). Beta formats are not billed at all, so state the exclusion explicitly. --- docs/best-practices/document-translations.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 049186ae..20b5b489 100644 --- a/docs/best-practices/document-translations.mdx +++ b/docs/best-practices/document-translations.mdx @@ -15,7 +15,7 @@ For DOCX and PPTX, our .NET, PHP and NodeJS client libraries offer functionality This allows users to translate files that might hit the size limit. ### Billing minimums -Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, or `.pdf` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. +Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, or `.pdf` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. Formats currently in beta are not billed and are not subject to this minimum. ### 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.