From 070bbc4b832d4a827ec983ee602cf803519eb239 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Fri, 27 Mar 2026 07:08:26 +0100 Subject: [PATCH] docs(v3-languages): add beta changelog page Adds a changelog for the v3/languages beta endpoints documenting planned breaking changes (field renames, endpoints field removal) and upcoming additions (status field, auto_detection feature, voice features). Links to it from the overview beta notice. Co-Authored-By: Claude Sonnet 4.6 --- ...etrieve-supported-languages-by-product.mdx | 3 +- .../languages/v3-languages-changelog.mdx | 93 +++++++++++++++++++ docs.json | 3 +- 3 files changed, 97 insertions(+), 2 deletions(-) create mode 100644 api-reference/languages/v3-languages-changelog.mdx diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-product.mdx index 8801dd5..11ce671 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-product.mdx @@ -15,7 +15,8 @@ Get information about all currently supported languages across all DeepL API pro 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. + 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. We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools: diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx new file mode 100644 index 0000000..5449a6d --- /dev/null +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -0,0 +1,93 @@ +--- +title: 'v3/languages changelog [BETA]' +sidebarTitle: 'Changelog' +description: 'Changes and planned updates to the v3/languages endpoints during the beta period.' +--- + + + These endpoints are in **BETA**. We will try to announce breaking changes here before they land, but cannot guarantee + advance notice. Do not use these endpoints in production. + + +## Changes since the initial beta release + +This section will list dated changes to the API since the initial beta release. + +### 19 March 2026 + +Initial beta release. + +## 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. + +--- + +### Breaking: remove `endpoints` from `/v3/languages/products` + +The `endpoints` array will be removed from each product object in the `/v3/languages/products` response. + +*Reasoning*: endpoint information is not useful programmatically. The applicable endpoints will still be described in +the documentation for each product. + +--- + +### New: language `status` field + +Language objects returned by `GET /v3/languages` will include an optional `status` field for languages not yet in general availability: + +```json +{ + "lang": "xyz", + "name": "Example Language", + "usable_as_source": true, + "usable_as_target": true, + "features": [], + "status": "beta" +} +``` + +Possible values: `"beta"`, `"early_access"`. Languages in GA omit this field entirely. + +--- + +### 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, +details are still being worked out. + +--- + +## Possible additions + +These are under consideration and may or may not land before GA. + +- **`native_name` field** on language objects — the language's name in that language (e.g. `"Deutsch"` for German). + +--- + +## 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. diff --git a/docs.json b/docs.json index d275cb1..6edbcbe 100644 --- a/docs.json +++ b/docs.json @@ -218,7 +218,8 @@ "api-reference/languages/retrieve-languages-by-product", "api-reference/languages/retrieve-products", "api-reference/languages/retrieve-language-pair-exceptions", - "api-reference/languages/migrate-from-v2-languages" + "api-reference/languages/migrate-from-v2-languages", + "api-reference/languages/v3-languages-changelog" ] } ]