Merge pull request #345 from DeepLcom/v3-langs/ga-phase-2

docs(v3-languages): promote to GA, deprecate v2/languages and v2/glossary-language-pairs

Author: daniel-jones-dev

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-resource) instead.
 </Info>
 
 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.

api-reference/languages.mdx

@@ -1,20 +1,16 @@
 ---
-title: "Retrieve languages"
+title: "Retrieve languages (v2)"
 sidebarTitle: "Overview"
-description: "API reference for retrieving supported languages with the DeepL API."
+description: "Reference for the deprecated v2/languages endpoint. Migrate to v3/languages for new integrations."
 ---
 
-Get all currently supported source and target languages that can be used for text and document translation.
+<Warning>
+  **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-resource) 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.
+</Warning>
 
-<Info>
-  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.
-</Info>
-<Info>
-  To get languages available for glossaries, please see [here](/api-reference/multilingual-glossaries).
-</Info>
-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).
+`GET /v2/languages` returns the source and target languages supported for text and document translation. New integrations should use `/v3/languages`, which exposes the same translation languages along with feature support for glossaries, voice, write, and other resources.
 
-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).
+For background on how DeepL adds new translation languages and language variants, see [the language release process](/docs/resources/language-release-process). For the auto-generated reference spec for this endpoint, see [Retrieve supported languages](/api-reference/languages/retrieve-supported-languages).
 
 <Tabs>
 <Tab title="cURL">

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."
 ---
 

api-reference/languages/retrieve-languages-by-resource.mdx

@@ -1,9 +1,5 @@
 ---
 openapi: get /v3/languages
 title: "Retrieve languages"
-tag: "BETA"
 ---
 
-<Info>
-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.
-</Info>

api-reference/languages/retrieve-resources.mdx

@@ -1,11 +1,6 @@
 ---
 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."
 ---
 
-<Info>
-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.
-</Info>
-

api-reference/languages/retrieve-supported-languages-by-resource.mdx

@@ -1,14 +1,13 @@
 ---
 title: 'Retrieve supported languages by resource'
-tag: "BETA"
 sidebarTitle: 'Overview'
-description: "Learn how to retrieve supported language and feature data across all DeepL API resources using the v3/languages endpoints."
+description: "Learn how to retrieve supported language and feature data across all DeepL API resources"
 ---
 
-Get information about all currently supported languages across all DeepL API resources.
-
 <Info>
-    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)).
+    The `/v3/languages` endpoints replace the deprecated `/v2/languages` and `/v2/glossary-language-pairs` endpoints.
+    If you're currently using either, see the [migration guide](/api-reference/languages/migrate-from-v2-languages) for
+    differences and code examples.
 </Info>
 
 We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:
@@ -33,11 +32,11 @@ are querying language support for:
 | `style_rules` | Style rules management via the `/v3/style_rules` endpoints |
 
 <Note>
-    `glossary` is a resource value indicating glossaries can be created for that language, and managed via the glossary
-    management endpoints.
+    `glossary` and `style_rules` are resource values indicating glossaries and style rules that can be created for that
+    language, and managed via the glossary and style rules management endpoints.
 
-    Support for glossaries within specific resources (for example text translation) is indicated by the `glossary`
-    feature value, explained in a later section.
+    Support for glossaries and style rules within specific resources (for example text translation) is indicated by the
+    `glossary` and `style_rules` feature value, explained in a later section.
 </Note>
 
 ## Basic example

api-reference/languages/retrieve-supported-languages.mdx

@@ -1,4 +1,12 @@
 ---
 openapi: get /v2/languages
-title: "Retrieve supported languages"
+title: "Retrieve supported languages (v2)"
+tag: "DEPRECATED"
 ---
+
+<Warning>
+  **`/v2/languages` is deprecated.** Use [`GET /v3/languages`](/api-reference/languages/retrieve-supported-languages-by-resource) instead. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+
+  We do not yet have a timeline for sunsetting /v2/languages, and we'll share more detail on this topic by the end of Q2 2026.
+</Warning>
+

api-reference/languages/v3-languages-changelog.mdx

@@ -1,18 +1,18 @@
 ---
 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, including the GA release and prior breaking changes.'
 ---
 
-<Info>
-  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.
-</Info>
-
 ## Changes since the initial beta release
 
-This section lists dated changes to the API since the initial beta release.
+This section lists dated changes to the API.
+
+### 18 May 2026 — General Availability
+
+`/v3/languages` is now generally available. The endpoint replaces the deprecated `/v2/languages` and `/v2/glossary-language-pairs`. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for differences and code examples.
+
+The breaking changes listed below were applied alongside the GA release.
 
 ### 5 May 2026
 
@@ -111,17 +111,3 @@ from `GET /v3/languages` are sufficient to determine feature support for all pai
 ### 19 March 2026
 
 Initial beta release.
-
----
-
-## 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-resource) and the auto-generated reference pages linked there.

api-reference/multilingual-glossaries/list-language-pairs-supported-by-glossaries.mdx

@@ -1,8 +1,13 @@
 ---
 openapi: "get /v2/glossary-language-pairs"
 title: "List language pairs supported for glossaries"
+tag: "DEPRECATED"
 playground: none
 ---
 
+<Warning>
+  **`/v2/glossary-language-pairs` is deprecated.** Use [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-resource) instead. See the [migration guide](/api-reference/languages/migrate-from-v2-languages) for details.
+</Warning>
+
 <Info>This endpoint returns all possible language pairs for glossaries.
 [This list of supported languages](/docs/getting-started/supported-languages) may also be useful.</Info>

api-reference/openapi.json

@@ -585,7 +585,7 @@
                     "example": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
                   },
                   "style_id": {
-                    "description": "Specify the [style rule list](/api-reference/style-rules) to use for the translation. \n\n**Important:**  The target language has to match the language of the style rule list. \n\n**Note:** Any request with the `style_id` parameter enabled will use `quality_optimized` models. Requests combining `style_id` and `model_type: latency_optimized` will be rejected.",
+                    "description": "Specify the [style rule list](/api-reference/style-rules) to use for the translation.\n\n**Important:**  The target language has to match the language of the style rule list.\n\n**Note:** Any request with the `style_id` parameter enabled will use `quality_optimized` models. Requests combining `style_id` and `model_type: latency_optimized` will be rejected.",
                     "type": "string",
                     "example": "7ff9bfd6-cd85-4190-8503-d6215a321519"
                   },
@@ -1220,11 +1220,12 @@
     },
     "/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\navailability including source and target roles.\n\nRetrieve the list of language pairs supported by the glossary feature.",
         "operationId": "listGlossaryLanguages",
         "responses": {
           "200": {
@@ -2623,11 +2624,13 @@
     },
     "/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)\ninstead. See the [migration guide](https://developers.deepl.com/api-reference/languages/migrate-from-v2-languages)\nfor details.",
+        "operationId": "getLanguagesV2",
         "parameters": [
           {
             "name": "type",
@@ -2864,10 +2867,8 @@
     "/v3/languages/resources": {
       "get": {
         "tags": [
-          "MetaInformation",
-          "beta"
+          "MetaInformation"
         ],
-        "x-beta": true,
         "summary": "Retrieve Language Resources",
         "operationId": "getLanguageResources",
         "description": "Returns all DeepL API resources and the features they support.\n\nFor each feature, the response indicates which languages must support it for the feature to be\navailable — source only (`needs_source_support`), target only (`needs_target_support`), or both.\nThis allows clients to determine feature availability for a language pair by checking the\nappropriate language's `features` object returned by `GET /v3/languages`.",
@@ -3014,10 +3015,8 @@
     "/v3/languages": {
       "get": {
         "tags": [
-          "MetaInformation",
-          "beta"
+          "MetaInformation"
         ],
-        "x-beta": true,
         "summary": "Retrieve Languages",
         "operationId": "getLanguages",
         "description": "Returns languages supported by the specified DeepL API resource. Each language indicates whether it can\nbe used as a source language, a target language, or both, along with the features it supports for that\nresource.",
@@ -4786,7 +4785,7 @@
     "securitySchemes": {
       "auth_header": {
         "type": "apiKey",
-        "description": "Authentication with `Authorization` header and  `DeepL-Auth-Key` authentication scheme. Example:  `DeepL-Auth-Key <api-key>`\n",
+        "description": "Authentication with `Authorization` header and `DeepL-Auth-Key` authentication scheme. Example: `DeepL-Auth-Key <api-key>`\n",
         "name": "Authorization",
         "in": "header",
         "x-default": "DeepL-Auth-Key "
@@ -6562,7 +6561,7 @@
         }
       },
       "Formality": {
-        "description": "Sets whether the translated text should lean towards formal or informal language.\nThis feature is only available for certain target languages. Setting this parameter \nwith a target language that does not support formality will fail, unless one of the \n`prefer_...` options are used.\nPossible options are:\n  * `default` (default)\n  * `more` - for a more formal language\n  * `less` - for a more informal language\n  * `prefer_more` - for a more formal language if available, otherwise fallback to default formality\n  * `prefer_less` - for a more informal language if available, otherwise fallback to default formality",
+        "description": "Sets whether the translated text should lean towards formal or informal language.\nThis feature is only available for certain target languages. Setting this parameter\nwith a target language that does not support formality will fail, unless one of the\n`prefer_...` options are used.\nPossible options are:\n  * `default` (default)\n  * `more` - for a more formal language\n  * `less` - for a more informal language\n  * `prefer_more` - for a more formal language if available, otherwise fallback to default formality\n  * `prefer_less` - for a more informal language if available, otherwise fallback to default formality",
         "type": "string",
         "enum": [
           "default",
@@ -6827,12 +6826,12 @@
         }
       },
       "OutlineDetectionOption": {
-        "description": "Disable the automatic detection of XML structure by setting the `outline_detection` parameter \nto `false` and selecting the tags that should be considered structure tags. This will split sentences \nusing the `splitting_tags` parameter.",
+        "description": "Disable the automatic detection of XML structure by setting the `outline_detection` parameter\nto `false` and selecting the tags that should be considered structure tags. This will split sentences\nusing the `splitting_tags` parameter.",
         "type": "boolean",
         "default": true
       },
       "OutlineDetectionOptionStr": {
-        "description": "Disable the automatic detection of XML structure by setting the `outline_detection` parameter \nto `false` and selecting the tags that should be considered structure tags. This will split sentences \nusing the `splitting_tags` parameter.",
+        "description": "Disable the automatic detection of XML structure by setting the `outline_detection` parameter\nto `false` and selecting the tags that should be considered structure tags. This will split sentences\nusing the `splitting_tags` parameter.",
         "type": "string",
         "default": "1",
         "enum": [
@@ -6855,12 +6854,12 @@
         }
       },
       "PreserveFormattingOption": {
-        "description": "Sets whether the translation engine should respect the original formatting, even if it would usually \ncorrect some aspects.",
+        "description": "Sets whether the translation engine should respect the original formatting, even if it would usually\ncorrect some aspects.",
         "type": "boolean",
         "default": false
       },
       "PreserveFormattingOptionStr": {
-        "description": "Sets whether the translation engine should respect the original formatting, even if it would usually \ncorrect some aspects.",
+        "description": "Sets whether the translation engine should respect the original formatting, even if it would usually\ncorrect some aspects.",
         "type": "string",
         "enum": [
           "0",
@@ -6869,11 +6868,11 @@
         "default": "0"
       },
       "ShowBilledCharacters": {
-        "description": "When true, the response will include the billed_characters parameter, giving the \nnumber of characters from the request that will be counted by DeepL for billing purposes.",
+        "description": "When true, the response will include the billed_characters parameter, giving the\nnumber of characters from the request that will be counted by DeepL for billing purposes.",
         "type": "boolean"
       },
       "SplitSentencesOption": {
-        "description": "Sets whether the translation engine should first split the input into sentences. \n\nPossible values are:\n  * 0 - no splitting at all, whole input is treated as one sentence\n  * 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines\n  * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines",
+        "description": "Sets whether the translation engine should first split the input into sentences.\n\nPossible values are:\n  * 0 - no splitting at all, whole input is treated as one sentence\n  * 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines\n  * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines",
         "type": "string",
         "enum": [
           "0",
@@ -6885,7 +6884,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-resource) (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).",
         "example": "EN"
       },
       "TranslationMemory": {
@@ -7059,7 +7058,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-resource) (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).",
         "example": "DE"
       },
       "TargetLanguageWrite": {