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..b2e83f2 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 @@ -128,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. @@ -150,25 +168,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..7a1c12e 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -13,9 +13,24 @@ 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 +### 22 April 2026 -Initial beta release. +**Breaking: renamed `required_on_source` / `required_on_target`** — the feature dependency flags on +`/v3/languages/products` have been renamed: + +| Old name | New name | +|---|---| +| `required_on_source` | `needs_source_support` | +| `required_on_target` | `needs_target_support` | + +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. + +**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`). ### 17 April 2026 @@ -24,33 +39,13 @@ 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. - ---- - -### Breaking: rename `required_on_source` / `required_on_target` - -The feature dependency flags on `/v3/languages/products` will be renamed: - -| Current 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. - ---- +### 19 March 2026 -### Breaking: remove `endpoints` from `/v3/languages/products` +Initial beta release. -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,10 +68,15 @@ Possible values: `"beta"`, `"early_access"`. Languages in GA omit this field ent --- -### New: `auto_detection` feature across multiple products +### 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` | -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`). +Update any code that checks for `"custom_instructions"` in a language's `features` array. --- 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'