diff --git a/api-reference/glossaries.mdx b/api-reference/glossaries.mdx index 994bd03..55267b5 100644 --- a/api-reference/glossaries.mdx +++ b/api-reference/glossaries.mdx @@ -9,6 +9,8 @@ description: "Manage glossaries using the v2 endpoints" This page documents `v2` glossary endpoints, legacy endpoints that let you create and manage glossaries for a single language pair. [See here](/api-reference/multilingual-glossaries) for information on current `v3` endpoints. Using `v3` allows you to create, manage, and edit glossaries with entries in multiple language pairs, while still supporting monolingual functionality. [See here](/api-reference/glossaries/v2-vs-v3-endpoints) for an overview of the difference. + +The `/v2/glossary-language-pairs` endpoint is also deprecated. Use [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-product) instead. This page describes how to use the `v2` endpoints to work with _monolingual_ glossaries - glossaries that map phrases in one language to phrases in another language. If you're new to glossaries, we suggest you use `v3` instead. diff --git a/api-reference/languages.mdx b/api-reference/languages.mdx index 70341d2..1fe074a 100644 --- a/api-reference/languages.mdx +++ b/api-reference/languages.mdx @@ -1,17 +1,15 @@ --- -title: "Retrieve languages" +title: "Retrieve languages (v2)" sidebarTitle: "Overview" -description: "API reference for retrieving supported languages with the DeepL API." +description: "API reference for the deprecated v2/languages endpoint." --- + + **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-product) instead, which covers all DeepL API resources and provides richer feature information. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details. + + Get all currently supported source and target languages that can be used for text and document translation. - - As of April 2025, supported languages for [text improvement](/api-reference/improve-text) (DeepL API for Write) have not yet been added to the `/languages` endpoint; we'll be extending the `/languages` endpoint in the near future to include this information. - - - To get languages available for glossaries, please see [here](/api-reference/multilingual-glossaries). - We also provide a spec that is auto-generated from DeepL's OpenAPI file. [You can find it here](/api-reference/languages/retrieve-supported-languages). To understand how we'll update the `/languages` endpoint 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/language-feature-use-cases.mdx b/api-reference/languages/language-feature-use-cases.mdx index 3d70738..09601b7 100644 --- a/api-reference/languages/language-feature-use-cases.mdx +++ b/api-reference/languages/language-feature-use-cases.mdx @@ -1,6 +1,5 @@ --- title: 'Common use cases' -tag: "BETA" description: "Pseudocode examples for common language and feature lookup patterns using the v3/languages endpoints." --- diff --git a/api-reference/languages/retrieve-languages-by-product.mdx b/api-reference/languages/retrieve-languages-by-product.mdx index 5ba9346..be1a0ba 100644 --- a/api-reference/languages/retrieve-languages-by-product.mdx +++ b/api-reference/languages/retrieve-languages-by-product.mdx @@ -1,9 +1,5 @@ --- openapi: get /v3/languages title: "Retrieve languages" -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-products.mdx b/api-reference/languages/retrieve-products.mdx index 3e74f17..231b647 100644 --- a/api-reference/languages/retrieve-products.mdx +++ b/api-reference/languages/retrieve-products.mdx @@ -1,10 +1,5 @@ --- 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 766edbf..3f9b73d 100644 --- a/api-reference/languages/retrieve-supported-languages-by-product.mdx +++ b/api-reference/languages/retrieve-supported-languages-by-product.mdx @@ -1,6 +1,5 @@ --- title: 'Retrieve supported languages by resource' -tag: "BETA" sidebarTitle: 'Overview' description: "API reference for retrieving supported languages with the DeepL API across all resources." --- @@ -9,15 +8,11 @@ Get information about all currently supported languages across all DeepL API res 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. + API resources. They replace the deprecated `/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. 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/retrieve-supported-languages.mdx b/api-reference/languages/retrieve-supported-languages.mdx index 4e04361..5fd3a58 100644 --- a/api-reference/languages/retrieve-supported-languages.mdx +++ b/api-reference/languages/retrieve-supported-languages.mdx @@ -1,4 +1,10 @@ --- openapi: get /v2/languages -title: "Retrieve supported languages" +title: "Retrieve supported languages (v2)" +tag: "DEPRECATED" --- + + + **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-product) instead. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details. + + diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx index 604a2bc..a3e4a4c 100644 --- a/api-reference/languages/v3-languages-changelog.mdx +++ b/api-reference/languages/v3-languages-changelog.mdx @@ -1,18 +1,12 @@ --- title: 'v3/languages changelog' -tag: "BETA" sidebarTitle: 'Changelog' -description: 'Changes and planned updates to the v3/languages endpoints during the beta period.' +description: 'Changes to the v3/languages endpoints since the initial beta release.' --- - - 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. +This section lists dated changes to the API since the initial beta release. ### 5 May 2026 diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index b74dbc2..4ec4917 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -928,10 +928,15 @@ paths: - auth_header: [ ] /v2/glossary-language-pairs: get: + deprecated: true tags: - ManageGlossaries summary: List Language Pairs Supported by Glossaries - description: Retrieve the list of language pairs supported by the glossary feature. + description: |- + **Deprecated.** Use `GET /v3/languages?resource=glossary` instead, which returns per-language + availability including source and target roles. + + Retrieve the list of language pairs supported by the glossary feature. operationId: listGlossaryLanguages responses: 200: @@ -1830,10 +1835,15 @@ paths: - auth_header: [ ] /v2/languages: get: + deprecated: true tags: - MetaInformation summary: Retrieve Supported Languages - operationId: getLanguages + description: |- + **Deprecated.** Use `GET /v3/languages?resource=translate_text` (or the appropriate resource) + instead. See the [migration guide](https://developers.deepl.com/api-reference/languages/migrate-from-v2-languages) + for details. + operationId: getLanguagesV2 parameters: - name: type in: query @@ -1970,8 +1980,6 @@ paths: get: tags: - MetaInformation - - beta - x-beta: true summary: Retrieve Language Resources operationId: getLanguageResources description: |- @@ -2075,8 +2083,6 @@ paths: get: tags: - MetaInformation - - beta - x-beta: true summary: Retrieve Languages operationId: getLanguages description: |- @@ -4958,7 +4964,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-product). example: EN TranslationMemory: type: object @@ -5130,7 +5136,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-product). example: DE TargetLanguageWrite: type: string diff --git a/docs.json b/docs.json index 5ffd8a4..633de96 100644 --- a/docs.json +++ b/docs.json @@ -247,18 +247,18 @@ { "group": "Languages", "pages": [ - "api-reference/languages", - "api-reference/languages/retrieve-supported-languages", + "api-reference/languages/retrieve-supported-languages-by-product", + "api-reference/languages/language-feature-use-cases", + "api-reference/languages/retrieve-languages-by-product", + "api-reference/languages/retrieve-products", + "api-reference/languages/migrate-from-v2-languages", + "api-reference/languages/v3-languages-changelog", { - "group": "Languages By Resource", - "tag": "BETA", + "group": "v2 Languages", + "tag": "DEPRECATED", "pages": [ - "api-reference/languages/retrieve-supported-languages-by-product", - "api-reference/languages/language-feature-use-cases", - "api-reference/languages/retrieve-languages-by-product", - "api-reference/languages/retrieve-products", - "api-reference/languages/migrate-from-v2-languages", - "api-reference/languages/v3-languages-changelog" + "api-reference/languages", + "api-reference/languages/retrieve-supported-languages" ], "drilldown": false } diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index c65c082..1b348d7 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -4,9 +4,20 @@ description: "The latest features and improvements in the DeepL API, plus what's rss: true --- + +## May 5 - v3/languages General Availability + +- [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-product) and [`GET /v3/languages/resources`](/api-reference/languages/retrieve-products) are now generally available. +- The `resource` query parameter replaces `product`. The `/v3/languages/products` endpoint has been renamed to `/v3/languages/resources`. +- The `features` field on language objects is now an object keyed by feature name (e.g. `{"formality": {"status": "stable"}}`), replacing the previous array of strings. +- Language objects now include a `status` field (`stable`, `beta`, `early_access`). +- A new `include` query parameter controls whether beta (`?include=beta`) or external-provider (`?include=external`) languages and features are returned. +- The `custom_instructions` feature key has been renamed to `style_rules`. The `custom_instructions` parameter on the translate endpoint is unaffected. +- **`/v2/languages` and `/v2/glossary-language-pairs` are now deprecated.** Migrate to `/v3/languages` — see the [migration guide](/api-reference/languages/migrate-from-v2-languages). + + - Support for uploading, modifying, and deleting [translation memories](/docs/learning-how-tos/examples-and-guides/how-to-use-translation-memories) via API -- `v3/languages` endpoint with improved language code handling and additional functionality - API key-level endpoint restrictions - Usage reporting by custom tag and language pair