From f063452e230795888bf799b401c1fdc84c0a3d2c Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Thu, 23 Apr 2026 10:57:30 +0200 Subject: [PATCH 1/5] docs(languages): record 22 April changes in changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - rename required_on_source/required_on_target → needs_source_support/needs_target_support - remove endpoints field from /v3/languages/products schema and examples - add auto_detection feature to products schema and example Co-Authored-By: Claude Sonnet 4.6 --- .../languages/language-feature-use-cases.mdx | 4 +- ...etrieve-supported-languages-by-product.mdx | 17 ++++---- .../languages/v3-languages-changelog.mdx | 36 ++++++---------- api-reference/openapi.yaml | 41 +++++++------------ 4 files changed, 39 insertions(+), 59 deletions(-) diff --git a/api-reference/languages/language-feature-use-cases.mdx b/api-reference/languages/language-feature-use-cases.mdx index 6fd32d5..511fd8c 100644 --- a/api-reference/languages/language-feature-use-cases.mdx +++ b/api-reference/languages/language-feature-use-cases.mdx @@ -145,9 +145,9 @@ target = languages.find(l => l.lang == target_lang) for feature in product.features: supported = true - if feature.required_on_source and not source.features.includes(feature.name): + if feature.needs_source_support and not source.features.includes(feature.name): supported = false - if feature.required_on_target and not target.features.includes(feature.name): + if feature.needs_target_support and not target.features.includes(feature.name): supported = false ``` diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-product.mdx index c7e89fb..0d663d0 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-product.mdx @@ -150,25 +150,28 @@ curl -X GET 'https://api.deepl.com/v3/languages/products' \ [ { "name": "translate_text", - "endpoints": ["v2/translate"], "features": [ { "name": "formality", - "required_on_target": true + "needs_target_support": true }, { "name": "custom_instructions", - "required_on_target": true + "needs_target_support": true }, { "name": "tag_handling", - "required_on_source": true, - "required_on_target": true + "needs_source_support": true, + "needs_target_support": true }, { "name": "glossary", - "required_on_source": true, - "required_on_target": true + "needs_source_support": true, + "needs_target_support": true + }, + { + "name": "auto_detection", + "needs_source_support": true } ] } diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index 9a94c3d..af8c6b4 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -24,33 +24,28 @@ pairs where feature support differs from what can be predicted from the individu the endpoint had no data to return. Remove any calls to this endpoint; the per-language `features` arrays from `GET /v3/languages` are sufficient to determine feature support for all pairs. -## Planned changes - -The following changes are planned before general availability. They are not yet live. +### 22 April 2026 ---- +**Breaking: renamed `required_on_source` / `required_on_target`** — the feature dependency flags on +`/v3/languages/products` have been renamed: -### Breaking: rename `required_on_source` / `required_on_target` - -The feature dependency flags on `/v3/languages/products` will be renamed: - -| Current name | New name | +| Old name | New name | |---|---| | `required_on_source` | `needs_source_support` | | `required_on_target` | `needs_target_support` | -The semantics are unchanged — only the field names differ. Update any code that reads these fields. - -*Reasoning*: "required" reads like a JSON schema constraint (mandatory field) rather than a language support check. +Semantics are unchanged. Update any code that reads these fields. ---- +**Breaking: removed `endpoints` from `/v3/languages/products`** — the `endpoints` array has been removed +from each product object. The applicable endpoints are still described in the documentation for each product. -### Breaking: remove `endpoints` from `/v3/languages/products` +**New: `auto_detection` feature** — a new `auto_detection` feature has been added across multiple products +to indicate whether a language can be auto-detected as the source. This is a source-only feature +(`needs_source_support: true`, `needs_target_support: false`). -The `endpoints` array will be removed from each product object in the `/v3/languages/products` response. +## Planned changes -*Reasoning*: endpoint information is not useful programmatically. The applicable endpoints will still be described in -the documentation for each product. +The following changes are planned before general availability. They are not yet live. --- @@ -73,13 +68,6 @@ Possible values: `"beta"`, `"early_access"`. Languages in GA omit this field ent --- -### New: `auto_detection` feature across multiple products - -An `auto_detection` feature will be added to indicate whether a language can be auto-detected as the source. -This is a source-only feature (`needs_source_support: true`, `needs_target_support: false`). - ---- - ### New: expanded Voice features The `voice` product will expose a richer set of features in `/v3/languages/products` and per-language `features` arrays, diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index ff919a7..16d85b3 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1970,10 +1970,10 @@ paths: summary: Retrieve Language Products operationId: getLanguageProducts description: |- - Returns all DeepL API products, including the API endpoints they expose, and the features they support. + Returns all DeepL API products and the features they support. For each feature, the response indicates which languages must support it for the feature to be - available — source only (`required_on_source`), target only (`required_on_target`), or both. + available — source only (`needs_source_support`), target only (`needs_target_support`), or both. This allows clients to determine feature availability for a language pair by checking the appropriate language's `features` array returned by `GET /v3/languages`. responses: @@ -1990,7 +1990,6 @@ paths: type: object required: - name - - endpoints - features properties: name: @@ -2004,13 +2003,6 @@ paths: - write - style_rules example: translate_text - endpoints: - description: API endpoints associated with this product. - type: array - items: - type: string - example: - - v2/translate features: description: |- Features supported by this product. Each feature indicates which languages @@ -2031,37 +2023,34 @@ paths: - glossary - writing_style - tone - required_on_source: + - auto_detection + needs_source_support: description: If `true`, the source language must support this feature for it to be available. Defaults to `false` if absent. type: boolean - required_on_target: + needs_target_support: description: If `true`, the target language must support this feature for it to be available. Defaults to `false` if absent. type: boolean example: - name: translate_text - endpoints: - - v2/translate features: - name: formality - required_on_target: true + needs_target_support: true - name: custom_instructions - required_on_target: true + needs_target_support: true - name: tag_handling - required_on_source: true - required_on_target: true + needs_source_support: true + needs_target_support: true - name: glossary - required_on_source: true - required_on_target: true + needs_source_support: true + needs_target_support: true + - name: auto_detection + needs_source_support: true - name: voice - endpoints: - - v3/voice/realtime features: - name: glossary - required_on_source: true - required_on_target: true + needs_source_support: true + needs_target_support: true - name: style_rules - endpoints: - - v3/style_rules features: [] 400: $ref: '#/components/responses/BadRequest' From 34d356136081fddbc6d94dcf3c86b2d9d301f3fa Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Thu, 23 Apr 2026 11:00:09 +0200 Subject: [PATCH 2/5] docs(languages): show changelog entries newest-first Co-Authored-By: Claude Sonnet 4.6 --- .../languages/v3-languages-changelog.mdx | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index af8c6b4..e7e8ad2 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -13,17 +13,6 @@ description: 'Changes and planned updates to the v3/languages endpoints during t This section will list dated changes to the API since the initial beta release. -### 19 March 2026 - -Initial beta release. - -### 17 April 2026 - -**Removed: `/v3/languages/exceptions`** — this endpoint has been removed. We no longer have any language -pairs where feature support differs from what can be predicted from the individual language objects, so -the endpoint had no data to return. Remove any calls to this endpoint; the per-language `features` arrays -from `GET /v3/languages` are sufficient to determine feature support for all pairs. - ### 22 April 2026 **Breaking: renamed `required_on_source` / `required_on_target`** — the feature dependency flags on @@ -43,6 +32,17 @@ from each product object. The applicable endpoints are still described in the do to indicate whether a language can be auto-detected as the source. This is a source-only feature (`needs_source_support: true`, `needs_target_support: false`). +### 17 April 2026 + +**Removed: `/v3/languages/exceptions`** — this endpoint has been removed. We no longer have any language +pairs where feature support differs from what can be predicted from the individual language objects, so +the endpoint had no data to return. Remove any calls to this endpoint; the per-language `features` arrays +from `GET /v3/languages` are sufficient to determine feature support for all pairs. + +### 19 March 2026 + +Initial beta release. + ## Planned changes The following changes are planned before general availability. They are not yet live. From eddce024db40385cc1ac1c523e1719f63fe7f5f6 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Thu, 23 Apr 2026 11:20:27 +0200 Subject: [PATCH 3/5] docs(languages): add style_rules product --- .../languages/retrieve-supported-languages-by-product.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-product.mdx index 0d663d0..e4e2f23 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-product.mdx @@ -38,6 +38,7 @@ are querying language support for: | `voice` | Speech transcription and translation via the `/v3/voice` endpoints | | `write` | Text improvement via the `/v2/write` endpoints | | `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints | +| `style_rules` | Style rules management via the `/v3/style_rules`endpoints | `glossary` is a product value indicating glossaries can be created for that language, and managed via the glossary From a1ee41d3e22119aebcae2fa6e2e8597146693051 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Thu, 23 Apr 2026 11:20:45 +0200 Subject: [PATCH 4/5] docs(languages): add feature reference table to overview Co-Authored-By: Claude Sonnet 4.6 --- ...etrieve-supported-languages-by-product.mdx | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-product.mdx index e4e2f23..b2e83f2 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-product.mdx @@ -129,12 +129,29 @@ To use a feature, one or both languages in the pair must support it. For example present in the target language's `features` array. - **Source-and-target**: `tag_handling` and `glossary` must be supported by both languages. Check that the feature is present in *both* the source and target language's `features` arrays. - -Source-only features are also supported by the schema, and may be introduced in future products. +- **Source-only**: `auto_detection` only needs to be supported by the source language. In the documentation for API features that are supported for only a subset of languages, we specify which language feature value to check, and whether to check the source language, target language, or both. +### Product feature reference + +The table below lists all feature values that can appear in a language's `features` array. + +| Feature | Check language support on | Products | Description | +|------------------------------|---------------------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. | +| `custom_instructions` | target | `translate_text` | Language supports custom instructions that guide how DeepL translates text. | +| `formality` | target | `translate_text`, `translate_document` | Language supports formality control — adjusting the output to use formal or informal register. | +| `glossary` | source + target | `translate_text`, `translate_document`, `voice` | Language can be used with a glossary to enforce specific terminology. Both the source and target language must support this for a glossary to be usable with a given pair. | +| `tag_handling` | source + target | `translate_text`, `translate_document` | Language supports tag-aware translation, preserving markup structure (e.g. HTML, XML) in the output. | +| `transcription` | source | `voice` | Language supports transcription from audio to text. | +| `transcription_external` | source | `voice` | Like `transcription`, but relies on using external service providers. | +| `translated_speech` | target | `voice` | Language supports conversion from translated text to audio output. | +| `translated_speech_external` | target | `voice` | Like `translated_speech`, but relies on using external service providers. | +| `tone` | target | `write` | Language supports tone selection (e.g. confident, diplomatic, enthusiastic). | +| `writing_style` | target | `write` | Language supports writing style selection (e.g. academic, casual, business). | + ## Retrieving products programmatically Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically. From 44e0292d946cc06b64e51b84782d2dc664fab99c Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Thu, 23 Apr 2026 11:28:59 +0200 Subject: [PATCH 5/5] docs(languages): add planned rename of custom_instructions feature Co-Authored-By: Claude Sonnet 4.6 --- api-reference/languages/v3-languages-changelog.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index e7e8ad2..7a1c12e 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -68,6 +68,18 @@ Possible values: `"beta"`, `"early_access"`. Languages in GA omit this field ent --- +### Breaking: rename `custom_instructions` feature to `style_rules` + +The `custom_instructions` feature value on `translate_text` will be renamed to `style_rules`: + +| Current value | New value | +|---|---| +| `custom_instructions` | `style_rules` | + +Update any code that checks for `"custom_instructions"` in a language's `features` array. + +--- + ### New: expanded Voice features The `voice` product will expose a richer set of features in `/v3/languages/products` and per-language `features` arrays,