From 17315fab14954dbe5abcf037ce04073740e46631 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Sun, 3 May 2026 11:55:35 +0200 Subject: [PATCH 1/4] docs(v3-languages): apply GA breaking changes (May 5 2026) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies all 5 planned changes shipping at GA: - Rename `product` → `resource` (query param + /products → /resources endpoint) - Replace `features` array with object (keys = feature names, values = {status}) - Add `status` field to language objects (stable/beta/early_access) - Add `include` query param (beta, external) - Rename `custom_instructions` feature → `style_rules` Updates changelog, overview, use-cases, migration guide, nav group name. openapi.json is regenerated by CI. Co-Authored-By: Claude Sonnet 4.6 --- .../languages/language-feature-use-cases.mdx | 55 ++++--- .../languages/migrate-from-v2-languages.mdx | 50 +++--- api-reference/languages/retrieve-products.mdx | 5 +- ...etrieve-supported-languages-by-product.mdx | 151 +++++++++++------- .../languages/v3-languages-changelog.mdx | 144 ++++++----------- api-reference/openapi.yaml | 123 +++++++++----- docs.json | 2 +- 7 files changed, 289 insertions(+), 241 deletions(-) diff --git a/api-reference/languages/language-feature-use-cases.mdx b/api-reference/languages/language-feature-use-cases.mdx index d7c8473a..3d707382 100644 --- a/api-reference/languages/language-feature-use-cases.mdx +++ b/api-reference/languages/language-feature-use-cases.mdx @@ -5,7 +5,7 @@ description: "Pseudocode examples for common language and feature lookup pattern --- This page shows how to use the `/v3/languages` endpoints for common integration tasks. Examples are written -as pseudocode and are product-agnostic unless otherwise noted. +as pseudocode and are resource-agnostic unless otherwise noted. For background on how features and feature dependency types work, see the [overview](/api-reference/languages/retrieve-supported-languages-by-product). @@ -14,11 +14,11 @@ For background on how features and feature dependency types work, see the ## Populate source and target language dropdowns -A single call to `GET /v3/languages` returns all languages for a product. Filter by `usable_as_source` and +A single call to `GET /v3/languages` returns all languages for a resource. Filter by `usable_as_source` and `usable_as_target` to populate each dropdown separately. ``` -GET /v3/languages?product=translate_text +GET /v3/languages?resource=translate_text languages = response @@ -34,15 +34,15 @@ render target_dropdown(target_options) ## Show formality options only when supported `formality` only needs to be supported by the target language. Check the selected target language's `features` -array — no need to look at the source language. +object — no need to look at the source language. ``` -GET /v3/languages?product=translate_text +GET /v3/languages?resource=translate_text languages = response target = languages.find(l => l.lang == selected_target_lang) -if target.features.includes("formality"): +if "formality" in target.features: show formality_selector // e.g. ["default", "more", "less"] else: hide formality_selector @@ -55,15 +55,15 @@ else: `glossary` must be supported by both languages. ``` -GET /v3/languages?product=translate_text +GET /v3/languages?resource=translate_text languages = response source = languages.find(l => l.lang == source_lang) target = languages.find(l => l.lang == target_lang) -glossary_allowed = source.features.includes("glossary") - and target.features.includes("glossary") +glossary_allowed = "glossary" in source.features + and "glossary" in target.features ``` --- @@ -73,34 +73,34 @@ glossary_allowed = source.features.includes("glossary") Filter to targets where both the source and target support the `glossary` feature. ``` -GET /v3/languages?product=translate_text +GET /v3/languages?resource=translate_text languages = response source_lang = "en" source = languages.find(l => l.lang == source_lang) -if not source.features.includes("glossary"): +if "glossary" not in source.features: return [] // source doesn't support glossary at all targets_with_glossary = languages .filter(l => l.usable_as_target) - .filter(l => l.features.includes("glossary")) + .filter(l => "glossary" in l.features) ``` --- -## Show writing style options for the Write product +## Show writing style options for the Write resource -`writing_style` is a target-only feature on the `write` product. Check the target language's `features` array. +`writing_style` is a target-only feature on the `write` resource. Check the target language's `features` object. ``` -GET /v3/languages?product=write +GET /v3/languages?resource=write languages = response target = languages.find(l => l.lang == selected_target_lang) -if target.features.includes("writing_style"): +if "writing_style" in target.features: show writing_style_selector else: hide writing_style_selector @@ -110,12 +110,12 @@ else: ## Check if style rules are available for a target language -Use `product=style_rules` to query which languages support style rules. Style rules are target-language only — check -that the target language is listed in the response. The `style_rules` product has no additional features, so only +Use `resource=style_rules` to query which languages support style rules. Style rules are target-language only — check +that the target language is listed in the response. The `style_rules` resource has no additional features, so only the language availability needs to be checked. ``` -GET /v3/languages?product=style_rules +GET /v3/languages?resource=style_rules languages = response target = languages.find(l => l.lang == selected_target_lang) @@ -130,25 +130,24 @@ else: ## Determine feature support programmatically -Use `/v3/languages/products` to drive feature checks at runtime — without hardcoding which features need +Use `/v3/languages/resources` to drive feature checks at runtime — without hardcoding which features need target-only or both-language support into your client. ``` -GET /v3/languages/products -GET /v3/languages?product=translate_text +GET /v3/languages/resources +GET /v3/languages?resource=translate_text -products = first response +resources = first response languages = second response -product = products.find(p => p.name == "translate_text") +resource = resources.find(r => r.name == "translate_text") source = languages.find(l => l.lang == source_lang) target = languages.find(l => l.lang == target_lang) -for feature in product.features: +for feature in resource.features: supported = true - if feature.needs_source_support and not source.features.includes(feature.name): + if feature.needs_source_support and feature.name not in source.features: supported = false - if feature.needs_target_support and not target.features.includes(feature.name): + if feature.needs_target_support and feature.name not in target.features: supported = false ``` - diff --git a/api-reference/languages/migrate-from-v2-languages.mdx b/api-reference/languages/migrate-from-v2-languages.mdx index 4b8036a4..df5eee12 100644 --- a/api-reference/languages/migrate-from-v2-languages.mdx +++ b/api-reference/languages/migrate-from-v2-languages.mdx @@ -20,18 +20,18 @@ GET /v2/languages?type=source GET /v2/languages?type=target ``` -v3 uses a single endpoint that returns all languages for a product, with each language indicating whether it is +v3 uses a single endpoint that returns all languages for a resource, with each language indicating whether it is usable as a source, a target, or both: ``` -GET /v3/languages?product=translate_text +GET /v3/languages?resource=translate_text ``` -### New product identifiers +### New resource identifiers -v2 languages are implicitly tied to text and document translation. v3 introduces an explicit `product` parameter that applies across all DeepL API products: +v2 languages are implicitly tied to text and document translation. v3 introduces an explicit `resource` parameter that applies across all DeepL API resources: -| v2 | v3 `product` value | +| v2 | v3 `resource` value | |---|---| | *(implicit, text/document translation only)* | `translate_text` | | *(implicit, text/document translation only)* | `translate_document` | @@ -43,16 +43,16 @@ The v3 endpoints replace both `/v2/languages` and `/v2/glossary-language-pairs`. ### Features instead of `supports_formality` -v2 target languages include a boolean `supports_formality` field. v3 replaces this with a `features` array that covers additional capabilities per product: +v2 target languages include a boolean `supports_formality` field. v3 replaces this with a `features` object that covers additional capabilities per resource: | v2 field | v3 equivalent | |---|---| -| `"supports_formality": true` | `"features": ["formality"]` on the language object | +| `"supports_formality": true` | `"formality"` key present in the language's `features` object | For example, querying languages for text translation: ```sh -curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \ +curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' ``` @@ -63,29 +63,39 @@ curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \ "name": "German", "usable_as_source": true, "usable_as_target": true, - "features": ["formality", "tag_handling", "glossary"] + "status": "stable", + "features": { + "formality": {"status": "stable"}, + "tag_handling": {"status": "stable"}, + "glossary": {"status": "stable"} + } }, { "lang": "en-US", "name": "English (American)", "usable_as_source": false, "usable_as_target": true, - "features": ["tag_handling", "glossary"] + "status": "stable", + "features": { + "tag_handling": {"status": "stable"}, + "glossary": {"status": "stable"} + } } ] ``` -The response indicates German supports `formality`, but English (American) does not. +The response indicates German supports `formality` (key present in `features`), but English (American) does not (key absent). -See the [overview](/api-reference/languages/retrieve-supported-languages-by-product) for the full list of features per product. +See the [overview](/api-reference/languages/retrieve-supported-languages-by-product) for the full list of features per resource. ### Response field names -| v2 field | v3 field | -|----------------------|------------------------| -| `language` | `lang` | -| `name` | `name` *(unchanged)* | -| `supports_formality` | `features["formality]` | +| v2 field | v3 field | +|----------------------|---------------------------------------------------| +| `language` | `lang` | +| `name` | `name` *(unchanged)* | +| `supports_formality` | `"formality"` key in `features` object | +| *(not present)* | `status` | ### Language code casing @@ -97,6 +107,6 @@ DeepL accepts language codes case-insensitively as input across all endpoints. H If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use one of the following: -- `GET /v3/languages?product=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Filter by `usable_as_source` and `usable_as_target` as needed. Any combination of a valid source and target language is a supported glossary language pair. -- `GET /v3/languages?product=translate_text` to check which languages support using a glossary during text translation. Languages that include `"glossary"` in their `features` array support the `glossary_id` parameter on the translate endpoint. -- Similarly, use `product=translate_document` to check glossary support for document translation. +- `GET /v3/languages?resource=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Filter by `usable_as_source` and `usable_as_target` as needed. Any combination of a valid source and target language is a supported glossary language pair. +- `GET /v3/languages?resource=translate_text` to check which languages support using a glossary during text translation. Languages with a `"glossary"` key in their `features` object support the `glossary_id` parameter on the translate endpoint. +- Similarly, use `resource=translate_document` to check glossary support for document translation. diff --git a/api-reference/languages/retrieve-products.mdx b/api-reference/languages/retrieve-products.mdx index 97e68d1e..3e74f17c 100644 --- a/api-reference/languages/retrieve-products.mdx +++ b/api-reference/languages/retrieve-products.mdx @@ -1,9 +1,10 @@ --- -openapi: get /v3/languages/products -title: "Retrieve language products" +openapi: get /v3/languages/resources +title: "Retrieve language resources" tag: "BETA" --- This endpoint is available for testing in BETA. Breaking changes may be pushed with little or no advance notice, and we provide no guarantees of stability. + diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-product.mdx index 2ff551ed..766edbfd 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-product.mdx @@ -1,15 +1,15 @@ --- -title: 'Retrieve supported languages by product' +title: 'Retrieve supported languages by resource' tag: "BETA" sidebarTitle: 'Overview' -description: "API reference for retrieving supported languages with the DeepL API across all products." +description: "API reference for retrieving supported languages with the DeepL API across all resources." --- -Get information about all currently supported languages across all DeepL API products. +Get information about all currently supported languages across all DeepL API resources. The `/v3/languages` endpoints provide a single source of truth for language and feature support across all DeepL - API products. They replace the `/v2/languages` and `/v2/glossary-language-pairs` endpoints. + API resources. They replace the `/v2/languages` and `/v2/glossary-language-pairs` endpoints. If you're currently using `/v2/languages` or `/v2/glossary-language-pairs`, see the [migration guide](/api-reference/languages/migrate-from-v2-languages) @@ -17,19 +17,19 @@ Get information about all currently supported languages across all DeepL API pro **These endpoints are available for testing in BETA.** Breaking changes may be pushed with little or no advance notice, and we provide no guarantees of stability. Please do not use `/v3/languages` in production. See the - [changelog](/api-reference/languages/v3-languages-changelog) for planned changes. + [changelog](/api-reference/languages/v3-languages-changelog) for recent changes. We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools: - [Retrieve languages](/api-reference/languages/retrieve-languages-by-product) -- [Retrieve products](/api-reference/languages/retrieve-products) +- [Retrieve resources](/api-reference/languages/retrieve-products) To understand how we'll update these endpoints when we add translation support for a new language or language variant, please see [this article](/docs/resources/language-release-process). -## Products list +## Resources list -To retrieve language support, decide which DeepL product you're building for, then call `GET /v3/languages` with -the appropriate `product` value. The `product` parameter is required and identifies which DeepL API product you +To retrieve language support, decide which DeepL resource you're building for, then call `GET /v3/languages` with +the appropriate `resource` value. The `resource` parameter is required and identifies which DeepL API resource you are querying language support for: | Value | Description | @@ -39,20 +39,20 @@ 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 | +| `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 + `glossary` is a resource value indicating glossaries can be created for that language, and managed via the glossary management endpoints. - Support for glossaries within specific products (for example text translation) is indicated by the `glossary` + Support for glossaries within specific resources (for example text translation) is indicated by the `glossary` feature value, explained in a later section. ## Basic example -Each language in the response includes a `features` array indicating which optional capabilities are available for that -language — see the [Product features](#product-features) section below for details. +Each language in the response includes a `features` object indicating which optional capabilities are available for that +language — see the [Resource features](#resource-features) section below for details. The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update your requests to use `https://api-free.deepl.com` instead. @@ -63,14 +63,14 @@ The following example responses are truncated; the full API responses can includ ```sh Example request: languages for text translation -curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \ +curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' ``` ```http Example request: languages for text translation -GET /v3/languages?product=translate_text HTTP/2 +GET /v3/languages?resource=translate_text HTTP/2 Host: api.deepl.com Authorization: DeepL-Auth-Key [yourAuthKey] User-Agent: YourApp/1.2.3 @@ -85,31 +85,34 @@ User-Agent: YourApp/1.2.3 "name": "German", "usable_as_source": true, "usable_as_target": true, - "features": [ - "formality", - "tag_handling", - "glossary" - ] + "status": "stable", + "features": { + "formality": {"status": "stable"}, + "tag_handling": {"status": "stable"}, + "glossary": {"status": "stable"} + } }, { "lang": "en", "name": "English", "usable_as_source": true, "usable_as_target": false, - "features": [ - "tag_handling", - "glossary" - ] + "status": "stable", + "features": { + "tag_handling": {"status": "stable"}, + "glossary": {"status": "stable"} + } }, { "lang": "en-US", "name": "English (American)", "usable_as_source": false, "usable_as_target": true, - "features": [ - "tag_handling", - "glossary" - ] + "status": "stable", + "features": { + "tag_handling": {"status": "stable"}, + "glossary": {"status": "stable"} + } } ] ``` @@ -119,49 +122,79 @@ User-Agent: YourApp/1.2.3 Language codes in the `lang` field follow [BCP 47](https://www.rfc-editor.org/rfc/rfc5646). The base language subtag is always present; script, region, and variant subtags are included where needed to distinguish variants. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details. -## Product features +## Resource features + +Each language object includes a `features` object indicating which optional capabilities are supported for that language +with the requested resource. Each key is a feature name; the value is an object with at least a `status` field. + +To check whether a feature is supported, check that the key exists in the `features` object: + +```json +// Feature supported: +"features": { "formality": { "status": "stable" } } -Each language object includes a `features` array indicating which optional capabilities are supported for that language -with the requested product. +// Feature not supported: +"features": {} +``` To use a feature, one or both languages in the pair must support it. For example, for text translation: - **Target-only**: `formality` only needs to be supported by the target language. Check that `"formality"` is - present in the target language's `features` array. + a key in the target language's `features` object. - **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. + feature key is present in *both* the source and target language's `features` objects. - **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. +which language feature key to check, and whether to check the source language, target language, or both. + +### Resource feature reference + +The table below lists all feature keys that can appear in a language's `features` object. -### Product feature reference +| Feature | Check language support on | Resources | Description | +|------------------------------|---------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. | +| `style_rules` | target | `translate_text` | Language supports style rules that guide how DeepL translates text. Used with the `custom_instructions` and `style_id` parameters on the translate endpoint. | +| `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 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 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). | -The table below lists all feature values that can appear in a language's `features` array. +## Filtering by availability -| 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). | +By default, `GET /v3/languages` returns only stable languages and features. Use the `include` query parameter +to request additional languages and features based on their availability status: + +| Value | Effect | +|---|---| +| `beta` | Includes languages and features in beta, in addition to stable | +| `external` | Includes features that rely on external providers (orthogonal to stability level) | + +Values can be combined with repeated parameters: `?include=beta&include=external`. + +The `status` field on each language object and each feature object indicates its availability: + +| Status | Meaning | +|---|---| +| `stable` | Generally available | +| `beta` | Available for testing; may change | +| `early_access` | Limited availability; may change | -## Retrieving products programmatically +## Retrieving resources programmatically -Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically. +Use the `/v3/languages/resources` endpoint to retrieve the list of resources and their features programmatically. For each feature, the response indicates which languages must support it for the feature to be available — source only, target only, or both — allowing clients to determine feature availability for a language pair -by checking the appropriate `features` arrays. +by checking the appropriate `features` objects. ```sh -curl -X GET 'https://api.deepl.com/v3/languages/products' \ +curl -X GET 'https://api.deepl.com/v3/languages/resources' \ --header 'Authorization: DeepL-Auth-Key [yourAuthKey]' ``` @@ -175,7 +208,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/products' \ "needs_target_support": true }, { - "name": "custom_instructions", + "name": "style_rules", "needs_target_support": true }, { @@ -201,7 +234,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/products' \ The v3 language endpoints are designed to be forward-compatible: -- New features may be added to the `features` array +- New feature keys may be added to the `features` object - New languages will be added as DeepL support expands - Existing fields will not be removed or changed in backwards-incompatible ways @@ -210,15 +243,15 @@ to beta). When this happens, it will still be accessible via `?include=beta`. We build your integration to handle languages disappearing from the response gracefully. - Build your integration to gracefully handle new BCP 47 `lang` codes and new values in the `features` array. Do not hardcode assumptions about the format of language codes -- see [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details. + Build your integration to gracefully handle new BCP 47 `lang` codes and new feature keys in the `features` object. Do not hardcode assumptions about the format of language codes -- see [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details. ## Best practices 1. **Cache responses**: Language support changes infrequently. Consider caching responses for up to 1 hour. -2. **Check features**: Always check the `features` array on language objects rather than assuming support (e.g. for formality, glossary use, or writing style). +2. **Check features**: Always check the `features` object on language objects rather than assuming support (e.g. for formality, glossary use, or writing style). -3. **Handle forward compatibility**: New languages and features may be added at any time. Build your integration to dynamically accept new `lang` codes and `features` values instead of maintaining a hardcoded allowlist. +3. **Handle forward compatibility**: New languages and features may be added at any time. Build your integration to dynamically accept new `lang` codes and new keys in the `features` object instead of maintaining a hardcoded allowlist. 4. **Use specific variants**: For target languages, prefer specific regional variants (e.g., `"en-US"`, `"en-GB"`) when the distinction matters to your users. diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index 9d54647a..604a2bc1 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -14,87 +14,30 @@ 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. -### 22 April 2026 - -**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 +### 5 May 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. - ---- - -### New: language `status` field - -Language objects will include a `status` field indicating availability: - -```json -{ - "lang": "xyz", - "name": "Example Language", - "usable_as_source": true, - "usable_as_target": true, - "features": [], - "status": "stable" -} -``` +**Breaking: renamed `product` to `resource`** — the `product` query parameter on `GET /v3/languages` has been +renamed to `resource`. The `/v3/languages/products` endpoint has been renamed to `/v3/languages/resources`. +Update all calls accordingly. -Possible values: `"stable"`, `"beta"`, `"early_access"`. - ---- - -### Breaking: `features` array replaced by dictionary - -The `features` property on languages will change from a list of strings to an object (dictionary). Each -key is a feature name; the value is an object with at least a `status` field. +**Breaking: `features` array replaced by object** — the `features` property on language objects has changed +from an array of strings to an object (dictionary). Each key is a feature name; the value is an object with +at least a `status` field. Instead of: ```json { "lang": "de", - "name": "German", - ... - "features": [ - "formality", - "tag_handling" - ] + "features": ["formality", "tag_handling"] } ``` -the following schema will be used: +the following schema is used: ```json { "lang": "de", - "name": "German", - ... "features": { "formality": {"status": "stable"}, "tag_handling": {"status": "stable"} @@ -102,55 +45,72 @@ the following schema will be used: } ``` -Feature objects may include additional fields beyond `status` in a future update. To check whether a feature is -supported for a language, check that the key exists in the `features` object. +To check whether a feature is supported, check that the key exists in the `features` object. ---- +**New: language `status` field** — language objects now include a `status` field indicating availability: + +```json +{ + "lang": "de", + "status": "stable", + "features": { ... } +} +``` -### New: `include` query parameter +Possible values: `"stable"`, `"beta"`, `"early_access"`. -`GET /v3/languages` will accept a new `include` query parameter. By default (no parameter), only -generally available languages and features are returned. The parameter accepts the following values: +**New: `include` query parameter** — `GET /v3/languages` now accepts an `include` query parameter. +By default (no parameter), only stable languages and features are returned. | Value | Effect | |---|---| | `beta` | Includes languages and features in beta, in addition to stable | -| `early_access` | Includes languages and features in early access and beta, in addition to stable | | `external` | Includes features that rely on external providers (orthogonal to stability level) | Values are composable via repeated parameters: `?include=beta&include=external`. -This parameter also controls whether beta and external features appear in the `features` dictionary — see the -`features` schema change above. - ---- +**Breaking: renamed `custom_instructions` feature to `style_rules`** — the `custom_instructions` feature +value returned by `GET /v3/languages` has been renamed to `style_rules`: -### Breaking: rename `product` to `resource` - -`resource` is a clearer name for what this is describing. +| Old value | New value | +|---|---| +| `custom_instructions` | `style_rules` | -This involves the following changes: -- move the `GET /v3/languages/products` endpoint to `GET /v3/languages/resources` -- rename the `GET /v3/languages` query parameter `product` to `resource` +This affects the `features` object returned per language and the feature list returned by +`GET /v3/languages/resources`. Note: the `custom_instructions` parameter on the translate endpoint +is not affected by this change. --- -### Breaking: rename `custom_instructions` feature to `style_rules` +### 22 April 2026 -The `custom_instructions` feature value on `translate_text` will be renamed to `style_rules`: +**Breaking: renamed `required_on_source` / `required_on_target`** — the feature dependency flags on +`/v3/languages/products` have been renamed: -| Current value | New value | +| Old name | New name | |---|---| -| `custom_instructions` | `style_rules` | +| `required_on_source` | `needs_source_support` | +| `required_on_target` | `needs_target_support` | -Update any code that checks for `"custom_instructions"` in a language's `features` array. +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: expanded Voice features +**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 `voice` product will expose a richer set of features in `/v3/languages/products` and per-language `features` arrays, -details are still being worked out. +### 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` objects +from `GET /v3/languages` are sufficient to determine feature support for all pairs. + +### 19 March 2026 + +Initial beta release. --- diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index 7f256225..b74dbc2b 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1966,21 +1966,21 @@ paths: $ref: '#/components/responses/TooManyRequests' security: - auth_header: [ ] - /v3/languages/products: + /v3/languages/resources: get: tags: - MetaInformation - beta x-beta: true - summary: Retrieve Language Products - operationId: getLanguageProducts + summary: Retrieve Language Resources + operationId: getLanguageResources description: |- - Returns all DeepL API products and the features they support. + Returns all DeepL API resources and the features they support. For each feature, the response indicates which languages must support it for the feature to be 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`. + appropriate language's `features` object returned by `GET /v3/languages`. responses: 200: description: JSON array where each item represents a DeepL API product. @@ -1998,7 +1998,7 @@ paths: - features properties: name: - description: The product identifier. + description: The resource identifier. type: string enum: - translate_text @@ -2010,7 +2010,7 @@ paths: example: translate_text features: description: |- - Features supported by this product. Each feature indicates which languages + Features supported by this resource. Each feature indicates which languages must support it for the feature to be available — source, target, or both. type: array items: @@ -2019,11 +2019,11 @@ paths: - name properties: name: - description: The feature identifier, corresponding to values in the `features` array returned by `GET /v3/languages`. + description: The feature identifier, corresponding to keys in the `features` object returned by `GET /v3/languages`. type: string enum: - formality - - custom_instructions + - style_rules - tag_handling - glossary - writing_style @@ -2040,7 +2040,7 @@ paths: features: - name: formality needs_target_support: true - - name: custom_instructions + - name: style_rules needs_target_support: true - name: tag_handling needs_source_support: true @@ -2080,11 +2080,11 @@ paths: summary: Retrieve Languages operationId: getLanguages description: |- - Returns languages supported by the specified DeepL API product. Each language indicates whether it can + Returns languages supported by the specified DeepL API resource. Each language indicates whether it can be used as a source language, a target language, or both, along with the features it supports for that - product. + resource. parameters: - - name: product + - name: resource in: query required: true schema: @@ -2098,8 +2098,27 @@ paths: - style_rules example: translate_text description: |- - The product to retrieve languages for. Supported values: `translate_text`, `translate_document`, + The resource to retrieve languages for. Supported values: `translate_text`, `translate_document`, `glossary`, `voice`, `write`, `style_rules`. + - name: include + in: query + required: false + schema: + type: array + items: + type: string + enum: + - beta + - external + style: form + explode: true + description: |- + Controls which languages and features are included in the response. By default, only stable + languages and features are returned. Values can be combined with repeated parameters + (e.g. `?include=beta&include=external`). + + - `beta`: Include languages and features in beta, in addition to stable + - `external`: Include features that rely on external providers (orthogonal to stability level) responses: 200: description: JSON array where each item represents a supported language. @@ -2118,6 +2137,7 @@ paths: - usable_as_source - usable_as_target - features + - status properties: lang: description: The language code (BCP 47). @@ -2128,31 +2148,46 @@ paths: type: string example: German usable_as_source: - description: Whether this language can be used as a source language with the specified product. + description: Whether this language can be used as a source language with the specified resource. type: boolean usable_as_target: - description: Whether this language can be used as a target language with the specified product. + description: Whether this language can be used as a target language with the specified resource. type: boolean + status: + description: Availability status of this language. + type: string + enum: + - stable + - beta + - early_access + example: stable features: description: |- - Features supported for this language with the specified product. Always present; - empty array if no optional features are supported. Consult `/v3/languages/products` + Features supported for this language with the specified resource. Always present; + empty object if no optional features are supported. Each key is a feature name; + the value is an object with at least a `status` field. Consult `GET /v3/languages/resources` to determine whether a feature must be present on the source language, target language, - or both for a given product. - type: array - items: - type: string - enum: - - formality - - custom_instructions - - tag_handling - - glossary - - writing_style - - tone + or both for a given resource. + type: object + additionalProperties: + type: object + required: + - status + properties: + status: + description: Availability status of this feature for this language. + type: string + enum: + - stable + - beta + - early_access example: - - formality - - tag_handling - - glossary + formality: + status: stable + tag_handling: + status: stable + glossary: + status: stable examples: translateTextLanguages: summary: Languages for text translation @@ -2161,24 +2196,34 @@ paths: name: German usable_as_source: true usable_as_target: true + status: stable features: - - formality - - tag_handling - - glossary + formality: + status: stable + tag_handling: + status: stable + glossary: + status: stable - lang: en name: English usable_as_source: true usable_as_target: false + status: stable features: - - tag_handling - - glossary + tag_handling: + status: stable + glossary: + status: stable - lang: en-US name: English (American) usable_as_source: false usable_as_target: true + status: stable features: - - tag_handling - - glossary + tag_handling: + status: stable + glossary: + status: stable 400: $ref: '#/components/responses/BadRequest' 401: diff --git a/docs.json b/docs.json index 47aa9a41..5ffd8a46 100644 --- a/docs.json +++ b/docs.json @@ -250,7 +250,7 @@ "api-reference/languages", "api-reference/languages/retrieve-supported-languages", { - "group": "Languages By Product", + "group": "Languages By Resource", "tag": "BETA", "pages": [ "api-reference/languages/retrieve-supported-languages-by-product", From ed55601aaea1957fdea219c5c827a6ce83ebde07 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Tue, 5 May 2026 14:26:14 +0200 Subject: [PATCH 2/4] style(v3-languages): apply editorial fixes from docs review Bold table headers, trim callout to 2 sentences, fix json->text on commented code block, replace -- with period, update descriptions to action-oriented form, fix future tense in changelog intro. Co-Authored-By: Claude Sonnet 4.6 --- .../languages/migrate-from-v2-languages.mdx | 6 ++--- api-reference/languages/retrieve-products.mdx | 1 + ...etrieve-supported-languages-by-product.mdx | 25 ++++++------------- .../languages/v3-languages-changelog.mdx | 8 +++--- 4 files changed, 16 insertions(+), 24 deletions(-) diff --git a/api-reference/languages/migrate-from-v2-languages.mdx b/api-reference/languages/migrate-from-v2-languages.mdx index df5eee12..d94d88c3 100644 --- a/api-reference/languages/migrate-from-v2-languages.mdx +++ b/api-reference/languages/migrate-from-v2-languages.mdx @@ -31,7 +31,7 @@ GET /v3/languages?resource=translate_text v2 languages are implicitly tied to text and document translation. v3 introduces an explicit `resource` parameter that applies across all DeepL API resources: -| v2 | v3 `resource` value | +| **v2** | **v3 `resource` value** | |---|---| | *(implicit, text/document translation only)* | `translate_text` | | *(implicit, text/document translation only)* | `translate_document` | @@ -45,7 +45,7 @@ The v3 endpoints replace both `/v2/languages` and `/v2/glossary-language-pairs`. v2 target languages include a boolean `supports_formality` field. v3 replaces this with a `features` object that covers additional capabilities per resource: -| v2 field | v3 equivalent | +| **v2 field** | **v3 equivalent** | |---|---| | `"supports_formality": true` | `"formality"` key present in the language's `features` object | @@ -90,7 +90,7 @@ See the [overview](/api-reference/languages/retrieve-supported-languages-by-prod ### Response field names -| v2 field | v3 field | +| **v2 field** | **v3 field** | |----------------------|---------------------------------------------------| | `language` | `lang` | | `name` | `name` *(unchanged)* | diff --git a/api-reference/languages/retrieve-products.mdx b/api-reference/languages/retrieve-products.mdx index 3e74f17c..51f8e10f 100644 --- a/api-reference/languages/retrieve-products.mdx +++ b/api-reference/languages/retrieve-products.mdx @@ -2,6 +2,7 @@ openapi: get /v3/languages/resources title: "Retrieve language resources" tag: "BETA" +description: "Learn how to retrieve the list of DeepL API resources and their supported language features." --- diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-product.mdx index 766edbfd..34a4cc91 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-product.mdx @@ -2,22 +2,13 @@ title: 'Retrieve supported languages by resource' tag: "BETA" sidebarTitle: 'Overview' -description: "API reference for retrieving supported languages with the DeepL API across all resources." +description: "Learn how to retrieve supported language and feature data across all DeepL API resources using the v3/languages endpoints." --- Get information about all currently supported languages across all DeepL API resources. - The `/v3/languages` endpoints provide a single source of truth for language and feature support across all DeepL - API resources. They replace the `/v2/languages` and `/v2/glossary-language-pairs` endpoints. - - If you're currently using `/v2/languages` or `/v2/glossary-language-pairs`, see the - [migration guide](/api-reference/languages/migrate-from-v2-languages) - for a full list of differences and code examples. - - **These endpoints are available for testing in BETA.** Breaking changes may be pushed with little or no advance - notice, and we provide no guarantees of stability. Please do not use `/v3/languages` in production. See the - [changelog](/api-reference/languages/v3-languages-changelog) for recent changes. + These **BETA** endpoints replace `/v2/languages` and `/v2/glossary-language-pairs` (see the [migration guide](/api-reference/languages/migrate-from-v2-languages)). Do not use them in production; breaking changes may be pushed without advance notice (see the [changelog](/api-reference/languages/v3-languages-changelog)). We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools: @@ -32,7 +23,7 @@ To retrieve language support, decide which DeepL resource you're building for, t the appropriate `resource` value. The `resource` parameter is required and identifies which DeepL API resource you are querying language support for: -| Value | Description | +| **Value** | **Description** | |---|---| | `translate_text` | Text translation via the `/v2/translate` endpoint | | `translate_document` | Document translation via the `/v2/document` endpoint | @@ -129,7 +120,7 @@ with the requested resource. Each key is a feature name; the value is an object To check whether a feature is supported, check that the key exists in the `features` object: -```json +```text // Feature supported: "features": { "formality": { "status": "stable" } } @@ -152,7 +143,7 @@ which language feature key to check, and whether to check the source language, t The table below lists all feature keys that can appear in a language's `features` object. -| Feature | Check language support on | Resources | Description | +| **Feature** | **Check language support on** | **Resources** | **Description** | |------------------------------|---------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. | | `style_rules` | target | `translate_text` | Language supports style rules that guide how DeepL translates text. Used with the `custom_instructions` and `style_id` parameters on the translate endpoint. | @@ -171,7 +162,7 @@ The table below lists all feature keys that can appear in a language's `features By default, `GET /v3/languages` returns only stable languages and features. Use the `include` query parameter to request additional languages and features based on their availability status: -| Value | Effect | +| **Value** | **Effect** | |---|---| | `beta` | Includes languages and features in beta, in addition to stable | | `external` | Includes features that rely on external providers (orthogonal to stability level) | @@ -180,7 +171,7 @@ Values can be combined with repeated parameters: `?include=beta&include=external The `status` field on each language object and each feature object indicates its availability: -| Status | Meaning | +| **Status** | **Meaning** | |---|---| | `stable` | Generally available | | `beta` | Available for testing; may change | @@ -243,7 +234,7 @@ to beta). When this happens, it will still be accessible via `?include=beta`. We build your integration to handle languages disappearing from the response gracefully. - Build your integration to gracefully handle new BCP 47 `lang` codes and new feature keys in the `features` object. Do not hardcode assumptions about the format of language codes -- see [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details. + Build your integration to gracefully handle new BCP 47 `lang` codes and new feature keys in the `features` object. Do not hardcode assumptions about the format of language codes. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details. ## Best practices diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index 604a2bc1..947c6d65 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -12,7 +12,7 @@ description: 'Changes and planned updates to the v3/languages endpoints during t ## Changes since the initial beta release -This section will list dated changes to the API since the initial beta release. +This section lists dated changes to the API since the initial beta release. ### 5 May 2026 @@ -62,7 +62,7 @@ Possible values: `"stable"`, `"beta"`, `"early_access"`. **New: `include` query parameter** — `GET /v3/languages` now accepts an `include` query parameter. By default (no parameter), only stable languages and features are returned. -| Value | Effect | +| **Value** | **Effect** | |---|---| | `beta` | Includes languages and features in beta, in addition to stable | | `external` | Includes features that rely on external providers (orthogonal to stability level) | @@ -72,7 +72,7 @@ Values are composable via repeated parameters: `?include=beta&include=external`. **Breaking: renamed `custom_instructions` feature to `style_rules`** — the `custom_instructions` feature value returned by `GET /v3/languages` has been renamed to `style_rules`: -| Old value | New value | +| **Old value** | **New value** | |---|---| | `custom_instructions` | `style_rules` | @@ -87,7 +87,7 @@ is not affected by this change. **Breaking: renamed `required_on_source` / `required_on_target`** — the feature dependency flags on `/v3/languages/products` have been renamed: -| Old name | New name | +| **Old name** | **New name** | |---|---| | `required_on_source` | `needs_source_support` | | `required_on_target` | `needs_target_support` | From bf2a104c2bb70999cac0048b43eef9afc134d2d1 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Tue, 5 May 2026 14:29:22 +0200 Subject: [PATCH 3/4] refactor(v3-languages): rename -by-product paths to -by-resource Rename retrieve-{supported-,}languages-by-product.mdx to -by-resource, update all internal links, and add redirects in docs.json. Co-Authored-By: Claude Sonnet 4.6 --- .../languages/language-feature-use-cases.mdx | 2 +- .../languages/migrate-from-v2-languages.mdx | 2 +- ...roduct.mdx => retrieve-languages-by-resource.mdx} | 0 ... => retrieve-supported-languages-by-resource.mdx} | 2 +- api-reference/languages/v3-languages-changelog.mdx | 2 +- api-reference/openapi.json | 4 ++-- api-reference/openapi.yaml | 4 ++-- docs.json | 12 ++++++++++-- 8 files changed, 18 insertions(+), 10 deletions(-) rename api-reference/languages/{retrieve-languages-by-product.mdx => retrieve-languages-by-resource.mdx} (100%) rename api-reference/languages/{retrieve-supported-languages-by-product.mdx => retrieve-supported-languages-by-resource.mdx} (99%) diff --git a/api-reference/languages/language-feature-use-cases.mdx b/api-reference/languages/language-feature-use-cases.mdx index 3d707382..6cde5ee6 100644 --- a/api-reference/languages/language-feature-use-cases.mdx +++ b/api-reference/languages/language-feature-use-cases.mdx @@ -8,7 +8,7 @@ This page shows how to use the `/v3/languages` endpoints for common integration as pseudocode and are resource-agnostic unless otherwise noted. For background on how features and feature dependency types work, see the -[overview](/api-reference/languages/retrieve-supported-languages-by-product). +[overview](/api-reference/languages/retrieve-supported-languages-by-resource). --- diff --git a/api-reference/languages/migrate-from-v2-languages.mdx b/api-reference/languages/migrate-from-v2-languages.mdx index d94d88c3..0c0e2037 100644 --- a/api-reference/languages/migrate-from-v2-languages.mdx +++ b/api-reference/languages/migrate-from-v2-languages.mdx @@ -86,7 +86,7 @@ curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \ The response indicates German supports `formality` (key present in `features`), but English (American) does not (key absent). -See the [overview](/api-reference/languages/retrieve-supported-languages-by-product) for the full list of features per resource. +See the [overview](/api-reference/languages/retrieve-supported-languages-by-resource) for the full list of features per resource. ### Response field names diff --git a/api-reference/languages/retrieve-languages-by-product.mdx b/api-reference/languages/retrieve-languages-by-resource.mdx similarity index 100% rename from api-reference/languages/retrieve-languages-by-product.mdx rename to api-reference/languages/retrieve-languages-by-resource.mdx diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-resource.mdx similarity index 99% rename from api-reference/languages/retrieve-supported-languages-by-product.mdx rename to api-reference/languages/retrieve-supported-languages-by-resource.mdx index 34a4cc91..ae9518ba 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-resource.mdx @@ -12,7 +12,7 @@ Get information about all currently supported languages across all DeepL API res We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools: -- [Retrieve languages](/api-reference/languages/retrieve-languages-by-product) +- [Retrieve languages](/api-reference/languages/retrieve-languages-by-resource) - [Retrieve resources](/api-reference/languages/retrieve-products) To understand how we'll update these endpoints when we add translation support for a new language or language variant, please see [this article](/docs/resources/language-release-process). diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index 947c6d65..a29e2413 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -124,4 +124,4 @@ These are under consideration and may or may not land before GA. ## Current beta state -For the current API contract, see the [overview](/api-reference/languages/retrieve-supported-languages-by-product) and the auto-generated reference pages linked there. +For the current API contract, see the [overview](/api-reference/languages/retrieve-supported-languages-by-resource) and the auto-generated reference pages linked there. diff --git a/api-reference/openapi.json b/api-reference/openapi.json index e782eaca..1b26bcc0 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -6586,7 +6586,7 @@ }, "SourceLanguage": { "type": "string", - "description": "Language of the text to be translated. If this parameter is omitted, the API will attempt to\ndetect the language of the text and translate it.\n\nFor the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).", + "description": "Language of the text to be translated. If this parameter is omitted, the API will attempt to\ndetect the language of the text and translate it.\n\nFor the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).", "example": "EN" }, "TranslationMemory": { @@ -6760,7 +6760,7 @@ }, "TargetLanguage": { "type": "string", - "description": "The language into which the text should be translated.\n\nFor the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).", + "description": "The language into which the text should be translated.\n\nFor the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).", "example": "DE" }, "TargetLanguageWrite": { diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index b74dbc2b..f08f18ac 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -4958,7 +4958,7 @@ components: Language of the text to be translated. If this parameter is omitted, the API will attempt to detect the language of the text and translate it. - For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta). + For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta). example: EN TranslationMemory: type: object @@ -5130,7 +5130,7 @@ components: description: |- The language into which the text should be translated. - For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta). + For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta). example: DE TargetLanguageWrite: type: string diff --git a/docs.json b/docs.json index 5ffd8a46..1a886ff1 100644 --- a/docs.json +++ b/docs.json @@ -253,9 +253,9 @@ "group": "Languages By Resource", "tag": "BETA", "pages": [ - "api-reference/languages/retrieve-supported-languages-by-product", + "api-reference/languages/retrieve-supported-languages-by-resource", "api-reference/languages/language-feature-use-cases", - "api-reference/languages/retrieve-languages-by-product", + "api-reference/languages/retrieve-languages-by-resource", "api-reference/languages/retrieve-products", "api-reference/languages/migrate-from-v2-languages", "api-reference/languages/v3-languages-changelog" @@ -351,6 +351,14 @@ } }, "redirects": [ + { + "source": "/api-reference/languages/retrieve-supported-languages-by-product", + "destination": "/api-reference/languages/retrieve-supported-languages-by-resource" + }, + { + "source": "/api-reference/languages/retrieve-languages-by-product", + "destination": "/api-reference/languages/retrieve-languages-by-resource" + }, { "source": "/docs/api-reference/improve-text/openapi-spec-for-text-improvement", "destination": "/api-reference/improve-text/request-text-improvement" From 41f9a1f3346bbd1dda7a236a8301f3cee36a67d9 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Tue, 5 May 2026 14:31:57 +0200 Subject: [PATCH 4/4] style(v3-languages): simplify include=external wording Co-Authored-By: Claude Sonnet 4.6 --- .../languages/retrieve-supported-languages-by-resource.mdx | 2 +- api-reference/languages/v3-languages-changelog.mdx | 2 +- api-reference/openapi.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/api-reference/languages/retrieve-supported-languages-by-resource.mdx b/api-reference/languages/retrieve-supported-languages-by-resource.mdx index ae9518ba..55f3f7cf 100644 --- a/api-reference/languages/retrieve-supported-languages-by-resource.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-resource.mdx @@ -165,7 +165,7 @@ to request additional languages and features based on their availability status: | **Value** | **Effect** | |---|---| | `beta` | Includes languages and features in beta, in addition to stable | -| `external` | Includes features that rely on external providers (orthogonal to stability level) | +| `external` | Includes features that rely on third-party service providers | Values can be combined with repeated parameters: `?include=beta&include=external`. diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index a29e2413..2cf7f2f9 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -65,7 +65,7 @@ By default (no parameter), only stable languages and features are returned. | **Value** | **Effect** | |---|---| | `beta` | Includes languages and features in beta, in addition to stable | -| `external` | Includes features that rely on external providers (orthogonal to stability level) | +| `external` | Includes features that rely on third-party service providers | Values are composable via repeated parameters: `?include=beta&include=external`. diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index f08f18ac..2567c3f8 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -2118,7 +2118,7 @@ paths: (e.g. `?include=beta&include=external`). - `beta`: Include languages and features in beta, in addition to stable - - `external`: Include features that rely on external providers (orthogonal to stability level) + - `external`: Include features that rely on third-party service providers responses: 200: description: JSON array where each item represents a supported language.