Skip to content

Commit e4691b1

Browse files
Daniel Jonesclaude
Daniel Jones
and
claude
committed
docs(v3-languages): promote to GA, deprecate v2/languages and v2/glossary-language-pairs
- Remove BETA tags and notices from all v3/languages docs - Restructure Languages nav: v3 pages promoted to primary, v2 moved to DEPRECATED subgroup - Add deprecated: true to GET /v2/languages and GET /v2/glossary-language-pairs in OpenAPI spec - Fix duplicate operationId: rename v2/languages operationId to getLanguagesV2 - Add deprecation Warning to v2/languages overview and auto-generated reference page - Add deprecation note to v2 glossaries overview for /v2/glossary-language-pairs - Add May 5 release notes entry covering all GA changes and deprecations - Remove v3/languages from "In active development" list Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 4048fc5 commit e4691b1

12 files changed

Lines changed: 59 additions & 58 deletions

‎api-reference/glossaries.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ description: "Manage glossaries using the v2 endpoints"
99
This page documents `v2` glossary endpoints, legacy endpoints that let you create and manage glossaries for a single language pair.
1010

1111
[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.
12+
13+
The `/v2/glossary-language-pairs` endpoint is also deprecated. Use [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-product) instead.
1214
</Info>
1315

1416
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‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,15 @@
11
---
2-
title: "Retrieve languages"
2+
title: "Retrieve languages (v2)"
33
sidebarTitle: "Overview"
4-
description: "API reference for retrieving supported languages with the DeepL API."
4+
description: "API reference for the deprecated v2/languages endpoint."
55
---
66

7+
<Warning>
8+
**`/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.
9+
</Warning>
10+
711
Get all currently supported source and target languages that can be used for text and document translation.
812

9-
<Info>
10-
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.
11-
</Info>
12-
<Info>
13-
To get languages available for glossaries, please see [here](/api-reference/multilingual-glossaries).
14-
</Info>
1513
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).
1614

1715
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).

‎api-reference/languages/language-feature-use-cases.mdx‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
title: 'Common use cases'
3-
tag: "BETA"
43
description: "Pseudocode examples for common language and feature lookup patterns using the v3/languages endpoints."
54
---
65

‎api-reference/languages/retrieve-languages-by-product.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,5 @@
11
---
22
openapi: get /v3/languages
33
title: "Retrieve languages"
4-
tag: "BETA"
54
---
65

7-
<Info>
8-
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.
9-
</Info>

‎api-reference/languages/retrieve-products.mdx‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
11
---
22
openapi: get /v3/languages/resources
33
title: "Retrieve language resources"
4-
tag: "BETA"
54
---
65

7-
<Info>
8-
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.
9-
</Info>
10-

‎api-reference/languages/retrieve-supported-languages-by-product.mdx‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
title: 'Retrieve supported languages by resource'
3-
tag: "BETA"
43
sidebarTitle: 'Overview'
54
description: "API reference for retrieving supported languages with the DeepL API across all resources."
65
---
@@ -9,15 +8,11 @@ Get information about all currently supported languages across all DeepL API res
98

109
<Info>
1110
The `/v3/languages` endpoints provide a single source of truth for language and feature support across all DeepL
12-
API resources. They replace the `/v2/languages` and `/v2/glossary-language-pairs` endpoints.
11+
API resources. They replace the deprecated `/v2/languages` and `/v2/glossary-language-pairs` endpoints.
1312

1413
If you're currently using `/v2/languages` or `/v2/glossary-language-pairs`, see the
1514
[migration guide](/api-reference/languages/migrate-from-v2-languages)
1615
for a full list of differences and code examples.
17-
18-
**These endpoints are available for testing in BETA.** Breaking changes may be pushed with little or no advance
19-
notice, and we provide no guarantees of stability. Please do not use `/v3/languages` in production. See the
20-
[changelog](/api-reference/languages/v3-languages-changelog) for recent changes.
2116
</Info>
2217

2318
We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
---
22
openapi: get /v2/languages
3-
title: "Retrieve supported languages"
3+
title: "Retrieve supported languages (v2)"
4+
tag: "DEPRECATED"
45
---
6+
7+
<Warning>
8+
**`/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.
9+
</Warning>
10+

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

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,12 @@
11
---
22
title: 'v3/languages changelog'
3-
tag: "BETA"
43
sidebarTitle: 'Changelog'
5-
description: 'Changes and planned updates to the v3/languages endpoints during the beta period.'
4+
description: 'Changes to the v3/languages endpoints since the initial beta release.'
65
---
76

8-
<Info>
9-
These endpoints are in **BETA**. We will try to announce breaking changes here before they land, but cannot guarantee
10-
advance notice. Do not use these endpoints in production.
11-
</Info>
12-
137
## Changes since the initial beta release
148

15-
This section will list dated changes to the API since the initial beta release.
9+
This section lists dated changes to the API since the initial beta release.
1610

1711
### 5 May 2026
1812

‎api-reference/openapi.json‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1220,11 +1220,12 @@
12201220
},
12211221
"/v2/glossary-language-pairs": {
12221222
"get": {
1223+
"deprecated": true,
12231224
"tags": [
12241225
"ManageGlossaries"
12251226
],
12261227
"summary": "List Language Pairs Supported by Glossaries",
1227-
"description": "Retrieve the list of language pairs supported by the glossary feature.",
1228+
"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.",
12281229
"operationId": "listGlossaryLanguages",
12291230
"responses": {
12301231
"200": {
@@ -2623,11 +2624,13 @@
26232624
},
26242625
"/v2/languages": {
26252626
"get": {
2627+
"deprecated": true,
26262628
"tags": [
26272629
"MetaInformation"
26282630
],
26292631
"summary": "Retrieve Supported Languages",
2630-
"operationId": "getLanguages",
2632+
"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.",
2633+
"operationId": "getLanguagesV2",
26312634
"parameters": [
26322635
{
26332636
"name": "type",
@@ -2864,10 +2867,8 @@
28642867
"/v3/languages/resources": {
28652868
"get": {
28662869
"tags": [
2867-
"MetaInformation",
2868-
"beta"
2870+
"MetaInformation"
28692871
],
2870-
"x-beta": true,
28712872
"summary": "Retrieve Language Resources",
28722873
"operationId": "getLanguageResources",
28732874
"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 \u2014 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 @@
30143015
"/v3/languages": {
30153016
"get": {
30163017
"tags": [
3017-
"MetaInformation",
3018-
"beta"
3018+
"MetaInformation"
30193019
],
3020-
"x-beta": true,
30213020
"summary": "Retrieve Languages",
30223021
"operationId": "getLanguages",
30233022
"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.",

‎api-reference/openapi.yaml‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -928,10 +928,15 @@ paths:
928928
- auth_header: [ ]
929929
/v2/glossary-language-pairs:
930930
get:
931+
deprecated: true
931932
tags:
932933
- ManageGlossaries
933934
summary: List Language Pairs Supported by Glossaries
934-
description: Retrieve the list of language pairs supported by the glossary feature.
935+
description: |-
936+
**Deprecated.** Use `GET /v3/languages?resource=glossary` instead, which returns per-language
937+
availability including source and target roles.
938+
939+
Retrieve the list of language pairs supported by the glossary feature.
935940
operationId: listGlossaryLanguages
936941
responses:
937942
200:
@@ -1830,10 +1835,15 @@ paths:
18301835
- auth_header: [ ]
18311836
/v2/languages:
18321837
get:
1838+
deprecated: true
18331839
tags:
18341840
- MetaInformation
18351841
summary: Retrieve Supported Languages
1836-
operationId: getLanguages
1842+
description: |-
1843+
**Deprecated.** Use `GET /v3/languages?resource=translate_text` (or the appropriate resource)
1844+
instead. See the [migration guide](https://developers.deepl.com/api-reference/languages/migrate-from-v2-languages)
1845+
for details.
1846+
operationId: getLanguagesV2
18371847
parameters:
18381848
- name: type
18391849
in: query
@@ -1970,8 +1980,6 @@ paths:
19701980
get:
19711981
tags:
19721982
- MetaInformation
1973-
- beta
1974-
x-beta: true
19751983
summary: Retrieve Language Resources
19761984
operationId: getLanguageResources
19771985
description: |-
@@ -2075,8 +2083,6 @@ paths:
20752083
get:
20762084
tags:
20772085
- MetaInformation
2078-
- beta
2079-
x-beta: true
20802086
summary: Retrieve Languages
20812087
operationId: getLanguages
20822088
description: |-

0 commit comments

Comments
 (0)