From b85bd3e6388b13d91b2924ba704b3b7f824aa1b7 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Fri, 23 Jan 2026 13:36:31 +0000
Subject: [PATCH 01/32] Documentation edits made through Mintlify web editor
---
...ve-supported-languages-by-product-beta.mdx | 471 ++++++++++++++++++
docs.json | 3 +-
2 files changed, 473 insertions(+), 1 deletion(-)
create mode 100644 api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
new file mode 100644
index 0000000..59c9973
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -0,0 +1,471 @@
+---
+title: 'Retrieve supported languages by product [BETA]'
+description: "API reference for retrieving supported languages with the DeepL API across all products."
+---
+
+Get comprehensive information about all currently supported source and target languages across all DeepL API products, including text translation, document translation, DeepL API for Write, DeepL Voice, and glossaries.
+
+
+ The `/v3/languages` endpoint provides a single source of truth for language and feature support across all DeepL API products. It replaces the `/v2/languages` and `/v2/glossary-language-pairs` endpoints with a unified, extensible design.
+
+
+
+ Unlike the v2 endpoint which required a `type` parameter to retrieve source or target languages separately, v3 returns all language information in a single response.
+
+
+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-v3).
+
+To understand how we'll update the `/v3/languages` endpoint when we add translation support for a new language or language variant, please see [this article](/docs/resources/language-release-process).
+
+
+
+
+The example below uses 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.
+
+
+ The example responses below have been shortened for clarity. The actual API response includes all supported languages.
+
+
+```sh Example request: All languages
+curl -X GET 'https://api.deepl.com/v3/languages' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+{
+ "source_languages": [
+ {
+ "code": "DE",
+ "name": "German",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ },
+ {
+ "code": "EN",
+ "name": "English",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ }
+ ],
+ "target_languages": [
+ {
+ "code": "EN-US",
+ "name": "English (American)",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ },
+ {
+ "code": "FR",
+ "name": "French",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ }
+ ]
+}
+```
+
+```sh Example request: Text translation with features
+curl -X GET 'https://api.deepl.com/v3/languages?product=translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+{
+ "source_languages": [
+ {
+ "code": "DE",
+ "name": "German"
+ },
+ {
+ "code": "EN",
+ "name": "English"
+ }
+ ],
+ "target_languages": [
+ {
+ "code": "DE",
+ "name": "German",
+ "features": ["formality"]
+ },
+ {
+ "code": "EN-US",
+ "name": "English (American)"
+ },
+ {
+ "code": "FR",
+ "name": "French",
+ "features": ["formality"]
+ }
+ ]
+}
+```
+
+```sh Example request: Source language filter
+curl -X GET 'https://api.deepl.com/v3/languages?product=translate&source_lang=DE' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+{
+ "source_languages": [
+ {
+ "code": "DE",
+ "name": "German"
+ }
+ ],
+ "target_languages": [
+ {
+ "code": "EN-US",
+ "name": "English (American)"
+ },
+ {
+ "code": "FR",
+ "name": "French",
+ "features": ["formality"]
+ }
+ ]
+}
+```
+
+
+
+
+ The example responses below have been shortened for clarity. The actual API response includes all supported languages.
+
+
+```http Example request: All languages
+GET /v3/languages HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+```json Example response
+{
+ "source_languages": [
+ {
+ "code": "DE",
+ "name": "German",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ },
+ {
+ "code": "FR",
+ "name": "French",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ }
+ ],
+ "target_languages": [
+ {
+ "code": "EN-GB",
+ "name": "English (British)",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ },
+ {
+ "code": "ES",
+ "name": "Spanish",
+ "products": ["translate", "glossary", "document", "voice", "write"]
+ }
+ ]
+}
+```
+
+```http Example request: Document translation with features
+GET /v3/languages?product=document HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+```json Example response
+{
+ "source_languages": [
+ {
+ "code": "DE",
+ "name": "German"
+ },
+ {
+ "code": "FR",
+ "name": "French"
+ }
+ ],
+ "target_languages": [
+ {
+ "code": "EN-GB",
+ "name": "English (British)"
+ },
+ {
+ "code": "ES",
+ "name": "Spanish",
+ "features": ["formality"]
+ }
+ ]
+}
+```
+
+
+
+## Response Structure
+
+The v3 languages endpoint returns a JSON object with two main arrays:
+
+### source_languages
+
+An array of source language objects, each containing:
+
+- **code**: The language code used in API requests (e.g., "DE", "EN", "FR")
+- **name**: The English name of the language (e.g., "German", "English", "French")
+- **products** (optional): An array of product names when no `product` query parameter is specified. Values: "translate", "glossary", "document", "voice", "write"
+- **features** (optional): An array of additional features supported by the language, only present when querying with specific products
+
+### target_languages
+
+An array of target language objects with the same structure as source languages. Target languages may include language variants (e.g., "EN-US", "EN-GB") that are grouped under a single base language for source languages (e.g., "EN").
+
+
+ When the `product` query parameter is specified, source languages do not include a `features` field. Features only appear on target languages for product-specific queries.
+
+
+## Query Parameters
+
+
+ Filter languages by product. Supported values: `translate`, `document`, `glossary`, `voice`, `write`.
+
+ When specified:
+ - Only languages supporting the product are returned
+ - The `products` field is omitted from the response
+ - Target languages may include a `features` array showing additional capabilities
+
+
+
+ Filter to a specific source language. Returns that source language and all valid target languages for it.
+
+ **Requirements:**
+ - Must be used with the `product` parameter
+ - Cannot be used together with `target_lang`
+ - Language code must be valid (e.g., "DE", "EN", "FR")
+
+
+
+ Filter to a specific target language. Returns that target language and all valid source languages for it.
+
+ **Requirements:**
+ - Must be used with the `product` parameter
+ - Cannot be used together with `source_lang`
+ - Language code must be valid (e.g., "DE", "EN-US", "FR")
+
+
+## Features Field
+
+The `features` array indicates additional capabilities supported by a target language for specific products:
+
+
+ An array of feature strings. Currently supported values:
+
+ - **`formality`**: The language supports formality control (formal/informal translation)
+
+ **When this field appears:**
+ - Only on target languages (never on source languages)
+ - Only when `product=translate` or `product=document`
+ - Omitted when no `product` parameter is specified
+ - Omitted when the language doesn't support any features
+
+
+## Understanding Language Support
+
+### Basic Language Support
+
+**Without filtering (no query parameters):**
+```javascript
+GET /v3/languages
+// Returns all languages with products array
+// Example: { "code": "DE", "name": "German", "products": ["translate", "document", ...] }
+```
+
+**With product filter:**
+```javascript
+GET /v3/languages?product=translate
+// Returns only languages supporting text translation
+// Source languages: no features field
+// Target languages: may include features array
+```
+
+**With source language filter:**
+```javascript
+GET /v3/languages?product=translate&source_lang=DE
+// Returns: DE as source + all valid target languages for DE
+// Respects language pair exceptions (e.g., unsupported combinations)
+```
+
+### Language Pair Exceptions
+
+Some product may support individual languages but not specific combinations. For example:
+- Voice may support DE→EN and FR→EN
+- But not support DE→FR
+
+When querying with filters, the endpoint automatically excludes unsupported pairs:
+```javascript
+GET /v3/languages?product=voice&source_lang=DE
+// Returns DE as source, but FR won't appear in targets if DE→FR is unsupported
+```
+
+### Source vs Target Language Variants
+
+Source languages use base codes (e.g., "EN"), while target languages may use variant codes (e.g., "EN-US", "EN-GB"):
+
+```javascript
+// Source language
+{ "code": "EN", "name": "English" }
+
+// Target languages
+{ "code": "EN-US", "name": "English (American)" }
+{ "code": "EN-GB", "name": "English (British)" }
+```
+
+## Use Cases
+
+### Dynamically Building Translation UI
+
+```javascript
+// Fetch all languages
+const response = await fetch('https://api.deepl.com/v3/languages', {
+ headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
+});
+const data = await response.json();
+
+// Filter by product in your UI
+const textSources = data.source_languages
+ .filter(lang => lang.products.includes('translate'));
+const textTargets = data.target_languages
+ .filter(lang => lang.products.includes('translate'));
+```
+
+### Checking Feature Support
+
+```javascript
+// Get translate languages with feature info
+const response = await fetch('https://api.deepl.com/v3/languages?product=translate', {
+ headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
+});
+const data = await response.json();
+
+// Find languages that support formality
+const formalityTargets = data.target_languages
+ .filter(lang => lang.features?.includes('formality'))
+ .map(lang => lang.code);
+// Example result: ["DE", "ES", "FR", "IT", "JA", "NL", "PL", "PT-BR", "PT-PT", "RU"]
+```
+
+### Validating Language Pairs
+
+```javascript
+// Check if a specific pair is valid for voice translation
+const response = await fetch(
+ 'https://api.deepl.com/v3/languages?product=voice&source_lang=DE',
+ { headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' } }
+);
+const data = await response.json();
+
+// Check if FR is a valid target
+const isFrenchSupported = data.target_languages.some(lang => lang.code === 'FR');
+```
+
+### Checking Product-Specific Support
+
+```javascript
+// Get languages for specific products
+const products = ['translate', 'document', 'voice', 'write', 'glossary'];
+
+for (const product of products) {
+ const response = await fetch(
+ `https://api.deepl.com/v3/languages?product=${product}`,
+ { headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' } }
+ );
+ const data = await response.json();
+ console.log(`${product}: ${data.source_languages.length} sources, ${data.target_languages.length} targets`);
+}
+```
+
+## Migration from v2
+
+If you're currently using the v2 `/languages` endpoint, here are the key differences:
+
+### Key Changes
+
+1. **No type parameter**: v3 returns both source and target languages in a single response (or filter with query params)
+2. **Products array**: Instead of booleans, products are listed as strings in an array
+3. **Features field**: Replaces `supports_formality` and is only present when needed
+4. **Unified endpoint**: Replaces both `/v2/languages` and `/v2/glossary-language-pairs`
+5. **Query parameters**: New filtering options for product, source_lang, and target_lang
+
+### Migration Example
+
+**v2 code:**
+```javascript
+// v2: Separate calls
+const sourceRes = await fetch('/v2/languages?type=source');
+const targetRes = await fetch('/v2/languages?type=target');
+const sources = await sourceRes.json();
+const targets = await targetRes.json();
+
+// Check formality
+const formalityLangs = targets.filter(lang => lang.supports_formality);
+```
+
+**v3 code:**
+```javascript
+// v3: Single call or filtered
+const response = await fetch('/v3/languages');
+const data = await response.json();
+
+// Access directly
+const sources = data.source_languages;
+const targets = data.target_languages;
+
+// Or filter by product with features
+const translateRes = await fetch('/v3/languages?product=translate');
+const translateData = await translateRes.json();
+const formalityLangs = translateData.target_languages
+ .filter(lang => lang.features?.includes('formality'));
+```
+
+## Error Responses
+
+The endpoint returns standard HTTP error codes:
+
+
+ Invalid query parameters:
+ - Unknown product value
+ - `source_lang` or `target_lang` used without `product`
+ - Both `source_lang` and `target_lang` specified
+ - Invalid language code
+
+
+
+ Missing or invalid authentication.
+
+
+
+ API key doesn't have access to this endpoint.
+
+
+## API Stability
+
+The v3 languages endpoint is designed to be forward-compatible:
+
+- New products may be added to the `products` array
+- New features may be added to the `features` array
+- New languages will be added to the arrays as DeepL support expands
+- Existing fields will not be removed or changed in backwards-incompatible ways
+- Client applications should ignore unknown values to maintain forward compatibility
+
+
+ As new DeepL products and features are released, they will be reflected in this endpoint automatically. Build your integration to gracefully handle new values in the `products` and `features` arrays.
+
+
+## Best Practices
+
+1. **Cache responses**: Language support changes infrequently. Consider caching responses for 1 hour (the endpoint includes cache headers).
+
+2. **Handle partial support**: Not all languages support all products. Always check the `products` array before assuming a feature is available.
+
+3. **Use query parameters**: Filter by product when you only need specific language lists to reduce response size.
+
+4. **Check features**: For translate and document products, check the `features` array on target languages to determine formality support.
+
+5. **Use specific variants**: For target languages, use specific variants (e.g., "EN-US", "EN-GB") when the distinction matters to your users.
+
+6. **Handle empty responses**: When using `source_lang` or `target_lang` filters, the response may return empty arrays if the language doesn't support the specified product.
diff --git a/docs.json b/docs.json
index 325e9b7..26d55e0 100644
--- a/docs.json
+++ b/docs.json
@@ -193,7 +193,8 @@
"group": "Retrieve languages",
"pages": [
"api-reference/languages",
- "api-reference/languages/retrieve-supported-languages"
+ "api-reference/languages/retrieve-supported-languages",
+ "api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta"
]
},
{
From b245a457ad5c2d924b4ba131cd10ab2328c1f814 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 24 Feb 2026 16:44:49 +0100
Subject: [PATCH 02/32] updates to v3/languages endpoints
---
.../migrate-from-v2-languages.mdx | 68 ++
.../retrieve-source-languages-beta.mdx | 4 +
...ve-supported-languages-by-product-beta.mdx | 585 ++++++++----------
.../retrieve-target-languages-beta.mdx | 4 +
api-reference/openapi.yaml | 296 +++++++++
docs.json | 5 +-
6 files changed, 629 insertions(+), 333 deletions(-)
create mode 100644 api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
create mode 100644 api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx
create mode 100644 api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
new file mode 100644
index 0000000..b4bd2f8
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -0,0 +1,68 @@
+---
+title: 'Migrating from v2/languages'
+description: "How to migrate from the v2/languages endpoint to the v3/languages endpoints."
+---
+
+This page covers the differences between the `/v2/languages` endpoint and the v3 endpoints, and how to update your integration.
+
+
+ Only `GET` requests are supported on the v3 endpoints. Unlike `/v2/languages`, POST is not supported.
+
+
+## What changed
+
+### Separate endpoints for source and target
+
+v2 uses a single endpoint with a `type` query parameter:
+
+```
+GET /v2/languages?type=source
+GET /v2/languages?type=target
+```
+
+v3 uses two dedicated endpoints:
+
+```
+GET /v3/languages/source
+GET /v3/languages/target
+```
+
+### New product 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 | v3 `product` value |
+|---|---|
+| *(implicit — text/document translation only)* | `translate_text` |
+| *(implicit — text/document translation only)* | `translate_document` |
+| *(not supported — separate `/v2/glossary-language-pairs` endpoint)* | `glossary` |
+| *(not supported)* | `voice` |
+| *(not supported)* | `write` |
+
+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 field | v3 equivalent |
+|---|---|
+| `"supports_formality": true` | `"features": ["formality"]` on target language (when `product` is specified) |
+
+The `features` array only appears on a language object when a `product` parameter is specified and the language supports at least one feature for that product. See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta) for the full list of features per product.
+
+### Flat array response
+
+v2 returns a flat JSON array. v3 also returns a flat array — but each endpoint returns only its own list (sources or targets), so there is no wrapper object.
+
+### Response field names
+
+| v2 field | v3 field |
+|---|---|
+| `language` | `code` |
+| `name` | `name` *(unchanged)* |
+| `supports_formality` | `features` *(array, product-specific)* |
+
+## Migrating glossary language pair queries
+
+If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use `/v3/languages/source` and `/v3/languages/target` with `product=glossary` instead.
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx
new file mode 100644
index 0000000..7a231ba
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages/source
+title: "Retrieve source languages [BETA]"
+---
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 59c9973..4734445 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -1,21 +1,72 @@
---
title: 'Retrieve supported languages by product [BETA]'
+sidebarTitle: 'Overview'
description: "API reference for retrieving supported languages with the DeepL API across all products."
---
-Get comprehensive information about all currently supported source and target languages across all DeepL API products, including text translation, document translation, DeepL API for Write, DeepL Voice, and glossaries.
+Get comprehensive information about all currently supported source and target languages across all DeepL API products, including text translation, document translation, glossaries, DeepL Voice, and DeepL Write.
- The `/v3/languages` endpoint provides a single source of truth for language and feature support across all DeepL API products. It replaces the `/v2/languages` and `/v2/glossary-language-pairs` endpoints with a unified, extensible design.
+ 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 with a unified, extensible design.
-
- Unlike the v2 endpoint which required a `type` parameter to retrieve source or target languages separately, v3 returns all language information in a single response.
-
+We also provide specs that are auto-generated from DeepL's OpenAPI file. You can find them here:
+- [Retrieve source languages](/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta)
+- [Retrieve target languages](/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta)
+
+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).
+
+If you're currently using `/v2/languages` or `/v2/glossary-language-pairs`, see the [migration guide](/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages) for a full list of differences and code examples.
+
+## Products
+
+The `product` query parameter identifies which DeepL API product you are querying language support for:
+
+| Value | Description |
+|---|---|
+| `translate_text` | Text translation via the `/v2/translate` endpoint |
+| `translate_document` | Document translation via the `/v2/document` endpoint |
+| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
+| `voice` | Speech-to-speech/text via the `/v3/voice` endpoints |
+| `write` | Text improvement via the `/v2/write` endpoints |
+
+
+ `glossary` appears both as a standalone product name and as a feature value on individual languages for other products (e.g. `voice`). As a feature, it indicates that the language supports use with a glossary for that product.
+
+
+## Product features
+
+When a `product` query parameter is specified, language objects may include a `features` array. The features that can appear depend on both the product and whether the language is a source or target language.
-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-v3).
+### Source language features
-To understand how we'll update the `/v3/languages` endpoint when we add translation support for a new language or language variant, please see [this article](/docs/resources/language-release-process).
+| Product | Feature |
+|---|---|
+| `translate_text` | `tag_handling`, `glossary_id` |
+| `translate_document` | `glossary_id` |
+| `glossary` | *(none)* |
+| `voice` | `glossary` |
+| `write` | *(none)* |
+
+### Target language features
+
+| Product | Feature |
+|---|---|
+| `translate_text` | `formality`, `tag_handling`, `glossary_id`, `custom_instructions` |
+| `translate_document` | `formality`, `glossary_id` |
+| `glossary` | *(none)* |
+| `voice` | `formality`, `glossary` |
+| `write` | `writing_style`, `tone` |
+
+Feature values are defined as follows:
+
+- **`formality`**: The language supports formality control (formal/informal)
+- **`tag_handling`**: The language supports XML/HTML tag handling in translation requests
+- **`glossary_id`**: The language supports use with a glossary (via `glossary_id` parameter)
+- **`custom_instructions`**: The language supports custom translation instructions
+- **`glossary`**: The language supports use with a glossary for voice translation
+- **`writing_style`**: The language supports writing style selection
+- **`tone`**: The language supports tone selection
@@ -26,101 +77,109 @@ The example below uses our API Pro endpoint `https://api.deepl.com`. If you're a
The example responses below have been shortened for clarity. The actual API response includes all supported languages.
-```sh Example request: All languages
-curl -X GET 'https://api.deepl.com/v3/languages' \
+```sh Example request: All source languages
+curl -X GET 'https://api.deepl.com/v3/languages/source' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```json Example response
-{
- "source_languages": [
- {
- "code": "DE",
- "name": "German",
- "products": ["translate", "glossary", "document", "voice", "write"]
- },
- {
- "code": "EN",
- "name": "English",
- "products": ["translate", "glossary", "document", "voice", "write"]
- }
- ],
- "target_languages": [
- {
- "code": "EN-US",
- "name": "English (American)",
- "products": ["translate", "glossary", "document", "voice", "write"]
- },
- {
- "code": "FR",
- "name": "French",
- "products": ["translate", "glossary", "document", "voice", "write"]
- }
- ]
-}
+[
+ {
+ "code": "de",
+ "name": "German",
+ "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
+ },
+ {
+ "code": "en",
+ "name": "English",
+ "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
+ }
+]
```
-```sh Example request: Text translation with features
-curl -X GET 'https://api.deepl.com/v3/languages?product=translate' \
+```sh Example request: Source languages for text translation (with features)
+curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```json Example response
-{
- "source_languages": [
- {
- "code": "DE",
- "name": "German"
- },
- {
- "code": "EN",
- "name": "English"
- }
- ],
- "target_languages": [
- {
- "code": "DE",
- "name": "German",
- "features": ["formality"]
- },
- {
- "code": "EN-US",
- "name": "English (American)"
- },
- {
- "code": "FR",
- "name": "French",
- "features": ["formality"]
- }
- ]
-}
+[
+ {
+ "code": "de",
+ "name": "German",
+ "features": ["tag_handling", "glossary_id"]
+ },
+ {
+ "code": "en",
+ "name": "English",
+ "features": ["tag_handling", "glossary_id"]
+ }
+]
```
-```sh Example request: Source language filter
-curl -X GET 'https://api.deepl.com/v3/languages?product=translate&source_lang=DE' \
+```sh Example request: All target languages
+curl -X GET 'https://api.deepl.com/v3/languages/target' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```json Example response
-{
- "source_languages": [
- {
- "code": "DE",
- "name": "German"
- }
- ],
- "target_languages": [
- {
- "code": "EN-US",
- "name": "English (American)"
- },
- {
- "code": "FR",
- "name": "French",
- "features": ["formality"]
- }
- ]
-}
+[
+ {
+ "code": "en-US",
+ "name": "English (American)",
+ "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
+ },
+ {
+ "code": "fr",
+ "name": "French",
+ "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
+ }
+]
+```
+
+```sh Example request: Target languages for text translation (with features)
+curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+[
+ {
+ "code": "de",
+ "name": "German",
+ "features": ["formality", "tag_handling", "glossary_id"]
+ },
+ {
+ "code": "en-US",
+ "name": "English (American)",
+ "features": ["tag_handling", "glossary_id"]
+ },
+ {
+ "code": "fr",
+ "name": "French",
+ "features": ["formality", "tag_handling", "glossary_id"]
+ }
+]
+```
+
+```sh Example request: Filter target languages by source
+curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&source_lang=de' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response
+[
+ {
+ "code": "en-US",
+ "name": "English (American)",
+ "features": ["tag_handling", "glossary_id"]
+ },
+ {
+ "code": "fr",
+ "name": "French",
+ "features": ["formality", "tag_handling", "glossary_id"]
+ }
+]
```
@@ -129,308 +188,173 @@ curl -X GET 'https://api.deepl.com/v3/languages?product=translate&source_lang=DE
The example responses below have been shortened for clarity. The actual API response includes all supported languages.
-```http Example request: All languages
-GET /v3/languages HTTP/2
+```http Example request: All source languages
+GET /v3/languages/source HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
+
```json Example response
-{
- "source_languages": [
- {
- "code": "DE",
- "name": "German",
- "products": ["translate", "glossary", "document", "voice", "write"]
- },
- {
- "code": "FR",
- "name": "French",
- "products": ["translate", "glossary", "document", "voice", "write"]
- }
- ],
- "target_languages": [
- {
- "code": "EN-GB",
- "name": "English (British)",
- "products": ["translate", "glossary", "document", "voice", "write"]
- },
- {
- "code": "ES",
- "name": "Spanish",
- "products": ["translate", "glossary", "document", "voice", "write"]
- }
- ]
-}
+[
+ {
+ "code": "de",
+ "name": "German",
+ "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
+ },
+ {
+ "code": "fr",
+ "name": "French",
+ "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
+ }
+]
```
-```http Example request: Document translation with features
-GET /v3/languages?product=document HTTP/2
+```http Example request: Target languages for document translation
+GET /v3/languages/target?product=translate_document HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
+
```json Example response
-{
- "source_languages": [
- {
- "code": "DE",
- "name": "German"
- },
- {
- "code": "FR",
- "name": "French"
- }
- ],
- "target_languages": [
- {
- "code": "EN-GB",
- "name": "English (British)"
- },
- {
- "code": "ES",
- "name": "Spanish",
- "features": ["formality"]
- }
- ]
-}
+[
+ {
+ "code": "en-GB",
+ "name": "English (British)",
+ "features": ["glossary_id"]
+ },
+ {
+ "code": "es",
+ "name": "Spanish",
+ "features": ["formality", "glossary_id"]
+ }
+]
```
-## Response Structure
+## Response structure
-The v3 languages endpoint returns a JSON object with two main arrays:
+Both endpoints return a flat JSON array of language objects. Each object contains:
-### source_languages
+- **`code`**: The language code used in API requests (e.g., `"de"`, `"en"`, `"fr"`)
+- **`name`**: The English name of the language (e.g., `"German"`, `"English"`, `"French"`)
+- **`products`** *(optional)*: An array of product identifiers indicating which products support this language. Only present when no `product` query parameter is specified.
+- **`features`** *(optional)*: An array of feature strings indicating additional capabilities for this language with the specified product. Only present when a `product` query parameter is specified and the language supports one or more features for that product.
-An array of source language objects, each containing:
+### Source vs target language codes
-- **code**: The language code used in API requests (e.g., "DE", "EN", "FR")
-- **name**: The English name of the language (e.g., "German", "English", "French")
-- **products** (optional): An array of product names when no `product` query parameter is specified. Values: "translate", "glossary", "document", "voice", "write"
-- **features** (optional): An array of additional features supported by the language, only present when querying with specific products
+Source languages use base codes (e.g., `"en"`), while target languages may use regional variant codes (e.g., `"en-US"`, `"en-GB"`):
-### target_languages
+```javascript
+// Source language
+{ "code": "en", "name": "English" }
-An array of target language objects with the same structure as source languages. Target languages may include language variants (e.g., "EN-US", "EN-GB") that are grouped under a single base language for source languages (e.g., "EN").
+// Target languages
+{ "code": "en-US", "name": "English (American)" }
+{ "code": "en-GB", "name": "English (British)" }
+```
-
- When the `product` query parameter is specified, source languages do not include a `features` field. Features only appear on target languages for product-specific queries.
-
+## Query parameters
-## Query Parameters
+### GET /v3/languages/source
- Filter languages by product. Supported values: `translate`, `document`, `glossary`, `voice`, `write`.
+ Filter languages by product. Supported values: `translate_text`, `translate_document`, `glossary`, `voice`, `write`.
When specified:
- - Only languages supporting the product are returned
+ - Only languages supporting that product are returned
- The `products` field is omitted from the response
- - Target languages may include a `features` array showing additional capabilities
-
-
-
- Filter to a specific source language. Returns that source language and all valid target languages for it.
-
- **Requirements:**
- - Must be used with the `product` parameter
- - Cannot be used together with `target_lang`
- - Language code must be valid (e.g., "DE", "EN", "FR")
+ - Source languages may include a `features` array for product-specific capabilities
- Filter to a specific target language. Returns that target language and all valid source languages for it.
+ Filter source languages to those compatible with a specific target language. Must be used together with `product`. Cannot be used together with `source_lang`.
- **Requirements:**
- - Must be used with the `product` parameter
- - Cannot be used together with `source_lang`
- - Language code must be valid (e.g., "DE", "EN-US", "FR")
+ - Language code must be valid (e.g., `"en"`, `"en-US"`, `"fr"`)
+ - Only returns source languages that form a supported language pair with the given target
-## Features Field
+### GET /v3/languages/target
-The `features` array indicates additional capabilities supported by a target language for specific products:
-
-
- An array of feature strings. Currently supported values:
-
- - **`formality`**: The language supports formality control (formal/informal translation)
+
+ Filter languages by product. Supported values: `translate_text`, `translate_document`, `glossary`, `voice`, `write`.
- **When this field appears:**
- - Only on target languages (never on source languages)
- - Only when `product=translate` or `product=document`
- - Omitted when no `product` parameter is specified
- - Omitted when the language doesn't support any features
+ When specified:
+ - Only languages supporting that product are returned
+ - The `products` field is omitted from the response
+ - Target languages may include a `features` array for product-specific capabilities
-## Understanding Language Support
-
-### Basic Language Support
-
-**Without filtering (no query parameters):**
-```javascript
-GET /v3/languages
-// Returns all languages with products array
-// Example: { "code": "DE", "name": "German", "products": ["translate", "document", ...] }
-```
-
-**With product filter:**
-```javascript
-GET /v3/languages?product=translate
-// Returns only languages supporting text translation
-// Source languages: no features field
-// Target languages: may include features array
-```
+
+ Filter target languages to those compatible with a specific source language. Must be used together with `product`. Cannot be used together with `target_lang`.
-**With source language filter:**
-```javascript
-GET /v3/languages?product=translate&source_lang=DE
-// Returns: DE as source + all valid target languages for DE
-// Respects language pair exceptions (e.g., unsupported combinations)
-```
+ - Language code must be valid (e.g., `"de"`, `"en"`, `"fr"`)
+ - Only returns target languages that form a supported language pair with the given source
+
-### Language Pair Exceptions
+## Language pair exceptions
-Some product may support individual languages but not specific combinations. For example:
-- Voice may support DE→EN and FR→EN
-- But not support DE→FR
+Some products may support individual languages but not every combination. For example, a voice product might support `de→en` and `fr→en`, but not `de→fr`. When querying with a language filter, unsupported pairs are automatically excluded:
-When querying with filters, the endpoint automatically excludes unsupported pairs:
```javascript
-GET /v3/languages?product=voice&source_lang=DE
-// Returns DE as source, but FR won't appear in targets if DE→FR is unsupported
+GET /v3/languages/target?product=voice&source_lang=de
+// Returns valid target languages for de, excluding any that de cannot be paired with
```
-### Source vs Target Language Variants
+## Use cases
-Source languages use base codes (e.g., "EN"), while target languages may use variant codes (e.g., "EN-US", "EN-GB"):
+### Building a translation UI
```javascript
-// Source language
-{ "code": "EN", "name": "English" }
-
-// Target languages
-{ "code": "EN-US", "name": "English (American)" }
-{ "code": "EN-GB", "name": "English (British)" }
+// Fetch source and target languages for text translation
+const [sourceRes, targetRes] = await Promise.all([
+ fetch('https://api.deepl.com/v3/languages/source?product=translate_text', {
+ headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
+ }),
+ fetch('https://api.deepl.com/v3/languages/target?product=translate_text', {
+ headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
+ })
+]);
+const sources = await sourceRes.json();
+const targets = await targetRes.json();
```
-## Use Cases
-
-### Dynamically Building Translation UI
+### Checking feature support
```javascript
-// Fetch all languages
-const response = await fetch('https://api.deepl.com/v3/languages', {
- headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
-});
-const data = await response.json();
-
-// Filter by product in your UI
-const textSources = data.source_languages
- .filter(lang => lang.products.includes('translate'));
-const textTargets = data.target_languages
- .filter(lang => lang.products.includes('translate'));
-```
-
-### Checking Feature Support
+// Find target languages that support formality for text translation
+const response = await fetch(
+ 'https://api.deepl.com/v3/languages/target?product=translate_text',
+ { headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' } }
+);
+const targets = await response.json();
-```javascript
-// Get translate languages with feature info
-const response = await fetch('https://api.deepl.com/v3/languages?product=translate', {
- headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
-});
-const data = await response.json();
-
-// Find languages that support formality
-const formalityTargets = data.target_languages
+const formalityTargets = targets
.filter(lang => lang.features?.includes('formality'))
.map(lang => lang.code);
-// Example result: ["DE", "ES", "FR", "IT", "JA", "NL", "PL", "PT-BR", "PT-PT", "RU"]
+// Example result: ["de", "es", "fr", "it", "ja", "nl", "pl", "pt-BR", "pt-PT", "ru"]
```
-### Validating Language Pairs
+### Validating a language pair
```javascript
-// Check if a specific pair is valid for voice translation
+// Check which targets are valid when source is de for voice
const response = await fetch(
- 'https://api.deepl.com/v3/languages?product=voice&source_lang=DE',
+ 'https://api.deepl.com/v3/languages/target?product=voice&source_lang=de',
{ headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' } }
);
-const data = await response.json();
-
-// Check if FR is a valid target
-const isFrenchSupported = data.target_languages.some(lang => lang.code === 'FR');
-```
-
-### Checking Product-Specific Support
-
-```javascript
-// Get languages for specific products
-const products = ['translate', 'document', 'voice', 'write', 'glossary'];
-
-for (const product of products) {
- const response = await fetch(
- `https://api.deepl.com/v3/languages?product=${product}`,
- { headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' } }
- );
- const data = await response.json();
- console.log(`${product}: ${data.source_languages.length} sources, ${data.target_languages.length} targets`);
-}
-```
-
-## Migration from v2
-
-If you're currently using the v2 `/languages` endpoint, here are the key differences:
-
-### Key Changes
-
-1. **No type parameter**: v3 returns both source and target languages in a single response (or filter with query params)
-2. **Products array**: Instead of booleans, products are listed as strings in an array
-3. **Features field**: Replaces `supports_formality` and is only present when needed
-4. **Unified endpoint**: Replaces both `/v2/languages` and `/v2/glossary-language-pairs`
-5. **Query parameters**: New filtering options for product, source_lang, and target_lang
-
-### Migration Example
-
-**v2 code:**
-```javascript
-// v2: Separate calls
-const sourceRes = await fetch('/v2/languages?type=source');
-const targetRes = await fetch('/v2/languages?type=target');
-const sources = await sourceRes.json();
-const targets = await targetRes.json();
-
-// Check formality
-const formalityLangs = targets.filter(lang => lang.supports_formality);
+const targets = await response.json();
+const isFrenchSupported = targets.some(lang => lang.code === 'fr');
```
-**v3 code:**
-```javascript
-// v3: Single call or filtered
-const response = await fetch('/v3/languages');
-const data = await response.json();
-
-// Access directly
-const sources = data.source_languages;
-const targets = data.target_languages;
-
-// Or filter by product with features
-const translateRes = await fetch('/v3/languages?product=translate');
-const translateData = await translateRes.json();
-const formalityLangs = translateData.target_languages
- .filter(lang => lang.features?.includes('formality'));
-```
-
-## Error Responses
-
-The endpoint returns standard HTTP error codes:
+## Error responses
Invalid query parameters:
- - Unknown product value
+ - Unknown `product` value
- `source_lang` or `target_lang` used without `product`
- - Both `source_lang` and `target_lang` specified
- Invalid language code
@@ -442,30 +366,27 @@ The endpoint returns standard HTTP error codes:
API key doesn't have access to this endpoint.
-## API Stability
+## API stability
-The v3 languages endpoint is designed to be forward-compatible:
+The v3 language endpoints are designed to be forward-compatible:
- New products may be added to the `products` array
- New features may be added to the `features` array
-- New languages will be added to the arrays as DeepL support expands
+- New languages will be added as DeepL support expands
- Existing fields will not be removed or changed in backwards-incompatible ways
-- Client applications should ignore unknown values to maintain forward compatibility
- As new DeepL products and features are released, they will be reflected in this endpoint automatically. Build your integration to gracefully handle new values in the `products` and `features` arrays.
+ Build your integration to gracefully handle new values in the `products` and `features` arrays.
-## Best Practices
-
-1. **Cache responses**: Language support changes infrequently. Consider caching responses for 1 hour (the endpoint includes cache headers).
+## Best practices
-2. **Handle partial support**: Not all languages support all products. Always check the `products` array before assuming a feature is available.
+1. **Cache responses**: Language support changes infrequently. Consider caching responses for up to 1 hour.
-3. **Use query parameters**: Filter by product when you only need specific language lists to reduce response size.
+2. **Filter by product**: Use the `product` parameter when you only need languages for a specific product — this reduces response size and includes feature information.
-4. **Check features**: For translate and document products, check the `features` array on target languages to determine formality support.
+3. **Check features**: Always check the `features` array on language objects rather than assuming support (e.g. for formality, glossary use, or writing style).
-5. **Use specific variants**: For target languages, use specific variants (e.g., "EN-US", "EN-GB") when the distinction matters to your users.
+4. **Handle forward compatibility**: Ignore unknown values in `products` and `features` arrays to remain compatible as new products and capabilities are added.
-6. **Handle empty responses**: When using `source_lang` or `target_lang` filters, the response may return empty arrays if the language doesn't support the specified product.
+5. **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/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx
new file mode 100644
index 0000000..6dcc26a
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages/target
+title: "Retrieve target languages [BETA]"
+---
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index ae87f39..d3411d4 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -1942,6 +1942,302 @@ paths:
$ref: '#/components/responses/TooManyRequests'
security:
- auth_header: [ ]
+ /v3/languages/source:
+ get:
+ tags:
+ - MetaInformation
+ summary: Retrieve Source Languages
+ operationId: getSourceLanguages
+ description: |-
+ Returns source languages supported by one or more DeepL API products.
+
+ When no `product` parameter is specified, each language includes a `products` array
+ indicating which products support it. When `product` is specified, only languages
+ for that product are returned, the `products` field is omitted, and source languages
+ may include a `features` array listing product-specific capabilities.
+ parameters:
+ - name: product
+ in: query
+ required: false
+ schema:
+ type: string
+ enum:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ description: |-
+ Filter languages by product. Supported values: `translate_text`, `translate_document`,
+ `glossary`, `voice`, `write`.
+ - name: target_lang
+ in: query
+ required: false
+ schema:
+ type: string
+ example: en-US
+ description: |-
+ Filter source languages to those compatible with a specific target language.
+ Must be used together with `product`. Language code must be valid (e.g. `en`, `en-US`, `fr`).
+ responses:
+ 200:
+ description: JSON array where each item represents a supported source language.
+ headers:
+ X-Trace-ID:
+ $ref: '#/components/headers/X-Trace-ID'
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ required:
+ - code
+ - name
+ properties:
+ code:
+ description: The language code of the given language.
+ type: string
+ example: de
+ name:
+ description: Name of the language in English.
+ type: string
+ example: German
+ products:
+ description: |-
+ Array of product identifiers indicating which products support this language.
+ Only present when no `product` query parameter is specified.
+ type: array
+ items:
+ type: string
+ enum:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ example:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ features:
+ description: |-
+ Array of feature strings indicating capabilities for this language with the
+ specified product. Only present when a `product` query parameter is specified
+ and the language supports one or more features for that product.
+ type: array
+ items:
+ type: string
+ enum:
+ - tag_handling
+ - glossary_id
+ - glossary
+ example:
+ - tag_handling
+ - glossary_id
+ examples:
+ allSourceLanguages:
+ summary: All source languages (no product filter)
+ value:
+ - code: de
+ name: German
+ products:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ - code: en
+ name: English
+ products:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ translateTextSources:
+ summary: Source languages for text translation
+ value:
+ - code: de
+ name: German
+ features:
+ - tag_handling
+ - glossary_id
+ - code: en
+ name: English
+ features:
+ - tag_handling
+ - glossary_id
+ 400:
+ $ref: '#/components/responses/BadRequest'
+ 401:
+ $ref: '#/components/responses/Unauthorized'
+ 403:
+ $ref: '#/components/responses/Forbidden'
+ 429:
+ $ref: '#/components/responses/TooManyRequests'
+ 500:
+ $ref: '#/components/responses/InternalServerError'
+ 503:
+ $ref: '#/components/responses/ServiceUnavailable'
+ security:
+ - auth_header: []
+ /v3/languages/target:
+ get:
+ tags:
+ - MetaInformation
+ summary: Retrieve Target Languages
+ operationId: getTargetLanguages
+ description: |-
+ Returns target languages supported by one or more DeepL API products.
+
+ When no `product` parameter is specified, each language includes a `products` array
+ indicating which products support it. When `product` is specified, only languages
+ for that product are returned, the `products` field is omitted, and target languages
+ may include a `features` array listing product-specific capabilities.
+ parameters:
+ - name: product
+ in: query
+ required: false
+ schema:
+ type: string
+ enum:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ description: |-
+ Filter languages by product. Supported values: `translate_text`, `translate_document`,
+ `glossary`, `voice`, `write`.
+ - name: source_lang
+ in: query
+ required: false
+ schema:
+ type: string
+ example: de
+ description: |-
+ Filter target languages to those compatible with a specific source language.
+ Must be used together with `product`. Language code must be valid (e.g. `de`, `en`, `fr`).
+ responses:
+ 200:
+ description: JSON array where each item represents a supported target language.
+ headers:
+ X-Trace-ID:
+ $ref: '#/components/headers/X-Trace-ID'
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ required:
+ - code
+ - name
+ properties:
+ code:
+ description: The language code of the given language.
+ type: string
+ example: en-US
+ name:
+ description: Name of the language in English.
+ type: string
+ example: English (American)
+ products:
+ description: |-
+ Array of product identifiers indicating which products support this language.
+ Only present when no `product` query parameter is specified.
+ type: array
+ items:
+ type: string
+ enum:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ example:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ features:
+ description: |-
+ Array of feature strings indicating capabilities for this language with the
+ specified product. Only present when a `product` query parameter is specified
+ and the language supports one or more features for that product.
+ type: array
+ items:
+ type: string
+ enum:
+ - formality
+ - tag_handling
+ - glossary_id
+ - custom_instructions
+ - glossary
+ - writing_style
+ - tone
+ example:
+ - formality
+ - tag_handling
+ - glossary_id
+ examples:
+ allTargetLanguages:
+ summary: All target languages (no product filter)
+ value:
+ - code: en-US
+ name: English (American)
+ products:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ - code: fr
+ name: French
+ products:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ translateTextTargets:
+ summary: Target languages for text translation
+ value:
+ - code: de
+ name: German
+ features:
+ - formality
+ - tag_handling
+ - glossary_id
+ - code: en-US
+ name: English (American)
+ features:
+ - tag_handling
+ - glossary_id
+ - code: fr
+ name: French
+ features:
+ - formality
+ - tag_handling
+ - glossary_id
+ 400:
+ $ref: '#/components/responses/BadRequest'
+ 401:
+ $ref: '#/components/responses/Unauthorized'
+ 403:
+ $ref: '#/components/responses/Forbidden'
+ 429:
+ $ref: '#/components/responses/TooManyRequests'
+ 500:
+ $ref: '#/components/responses/InternalServerError'
+ 503:
+ $ref: '#/components/responses/ServiceUnavailable'
+ security:
+ - auth_header: []
/v3/style_rules:
get:
summary: Retrieve style rule lists
diff --git a/docs.json b/docs.json
index 26d55e0..0c06cfc 100644
--- a/docs.json
+++ b/docs.json
@@ -194,7 +194,10 @@
"pages": [
"api-reference/languages",
"api-reference/languages/retrieve-supported-languages",
- "api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta"
+ "api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
+ "api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta",
+ "api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta",
+ "api-reference/api-reference/retrieve-languages/migrate-from-v2-languages"
]
},
{
From af0c7bb22a90e301aa90e04e43aa72bb4d880b08 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 24 Feb 2026 16:56:57 +0100
Subject: [PATCH 03/32] move v2 pages to legacy area
---
api-reference/languages.mdx | 8 ++++----
.../languages/retrieve-supported-languages.mdx | 4 ++--
docs.json | 11 ++++++++---
3 files changed, 14 insertions(+), 9 deletions(-)
diff --git a/api-reference/languages.mdx b/api-reference/languages.mdx
index 9097163..a2889e9 100644
--- a/api-reference/languages.mdx
+++ b/api-reference/languages.mdx
@@ -1,7 +1,7 @@
---
-title: "Retrieve languages"
-sidebarTitle: "Overview"
-description: "API reference for retrieving supported languages with the DeepL API."
+title: "Retrieve languages (legacy)"
+sidebarTitle: "Overview (legacy)"
+description: "API reference for retrieving supported languages with the DeepL API using the v2 endpoint."
---
Get all currently supported source and target languages that can be used for text and document translation.
@@ -210,7 +210,7 @@ curl -X GET 'https://api.deepl.com/v2/languages?type=target' \
```http Example request: supported target languages
GET /v2/languages?type=target HTTP/2
Host: api.deepl.com
-Authorization: DeepL-Auth-Key [yourAuthKey]
+Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
```json Example response
diff --git a/api-reference/languages/retrieve-supported-languages.mdx b/api-reference/languages/retrieve-supported-languages.mdx
index 13b12c4..616bddb 100644
--- a/api-reference/languages/retrieve-supported-languages.mdx
+++ b/api-reference/languages/retrieve-supported-languages.mdx
@@ -1,4 +1,4 @@
---
openapi: get /v2/languages
-title: "Retrieve supported languages"
----
\ No newline at end of file
+title: "Retrieve supported languages (legacy)"
+---
diff --git a/docs.json b/docs.json
index 0c06cfc..b0c821d 100644
--- a/docs.json
+++ b/docs.json
@@ -192,12 +192,17 @@
{
"group": "Retrieve languages",
"pages": [
- "api-reference/languages",
- "api-reference/languages/retrieve-supported-languages",
"api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
"api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta",
"api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta",
- "api-reference/api-reference/retrieve-languages/migrate-from-v2-languages"
+ "api-reference/api-reference/retrieve-languages/migrate-from-v2-languages",
+ {
+ "group": "v2 (Legacy)",
+ "pages": [
+ "api-reference/languages",
+ "api-reference/languages/retrieve-supported-languages"
+ ]
+ }
]
},
{
From 3f433963dd5406d122afa71fc062679a83c8f95b Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 24 Feb 2026 16:57:15 +0100
Subject: [PATCH 04/32] consistent feature name "glossary_id"
---
.../retrieve-supported-languages-by-product-beta.mdx | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 4734445..e9a0f4d 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -45,7 +45,7 @@ When a `product` query parameter is specified, language objects may include a `f
| `translate_text` | `tag_handling`, `glossary_id` |
| `translate_document` | `glossary_id` |
| `glossary` | *(none)* |
-| `voice` | `glossary` |
+| `voice` | `glossary_id` |
| `write` | *(none)* |
### Target language features
@@ -55,7 +55,7 @@ When a `product` query parameter is specified, language objects may include a `f
| `translate_text` | `formality`, `tag_handling`, `glossary_id`, `custom_instructions` |
| `translate_document` | `formality`, `glossary_id` |
| `glossary` | *(none)* |
-| `voice` | `formality`, `glossary` |
+| `voice` | `formality`, `glossary_id` |
| `write` | `writing_style`, `tone` |
Feature values are defined as follows:
@@ -64,7 +64,6 @@ Feature values are defined as follows:
- **`tag_handling`**: The language supports XML/HTML tag handling in translation requests
- **`glossary_id`**: The language supports use with a glossary (via `glossary_id` parameter)
- **`custom_instructions`**: The language supports custom translation instructions
-- **`glossary`**: The language supports use with a glossary for voice translation
- **`writing_style`**: The language supports writing style selection
- **`tone`**: The language supports tone selection
From f9877b483018be95408ac0c5c4081b051fe63359 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 24 Feb 2026 17:12:48 +0100
Subject: [PATCH 05/32] simple examples
---
...ve-supported-languages-by-product-beta.mdx | 248 ++++++------------
1 file changed, 77 insertions(+), 171 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index e9a0f4d..45226bc 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -4,10 +4,16 @@ sidebarTitle: 'Overview'
description: "API reference for retrieving supported languages with the DeepL API across all products."
---
-Get comprehensive information about all currently supported source and target languages across all DeepL API products, including text translation, document translation, glossaries, DeepL Voice, and DeepL Write.
+Get information about all currently supported source and target languages across all DeepL API products, including
+text translation, document translation, glossaries, DeepL Voice, and DeepL Write.
- 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 with a unified, extensible design.
+ 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.
+
+ If you're currently using `/v2/languages` or `/v2/glossary-language-pairs`, see the
+ [migration guide](/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages)
+ for a full list of differences and code examples.
We also provide specs that are auto-generated from DeepL's OpenAPI file. You can find them here:
@@ -16,9 +22,75 @@ We also provide specs that are auto-generated from DeepL's OpenAPI file. You can
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).
-If you're currently using `/v2/languages` or `/v2/glossary-language-pairs`, see the [migration guide](/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages) for a full list of differences and code examples.
+## Basic example
+
+You can call the `/v3/languages/source` and endpoint to retrieve a list of all supported source languages, and the
+`/v3/languages/target` endpoint to retrieve a list of all supported target languages.
-## Products
+
+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.
+
+
+
+```sh Example request: supported source languages
+curl -X GET 'https://api.deepl.com/v3/languages/source' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+
+
+```http Example request: supported source languages
+GET /v3/languages/source HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+
+
+```json Example response
+[
+ { "code": "de", "name": "German", "products": ["translate_text", "translate_document", "glossary", "voice", "write"] },
+ { "code": "en", "name": "English", "products": ["translate_text", "translate_document", "glossary", "voice", "write"] }
+]
+```
+
+
+
+## Filtering by product
+
+When the `product` query parameter is specified, only languages supporting that product are returned.
+Additionally, the `products` array is replaced by a `features` array indicating which product-specific capabilities that
+language supports:
+
+
+
+
+```sh Example request: target languages for text translation
+curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+
+
+
+```http Example request: target languages for text translation
+GET /v3/languages/target?product=translate_text HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+
+
+
+```json Example response
+[
+ { "code": "de", "name": "German", "features": ["formality", "tag_handling", "glossary_id"] },
+ { "code": "en-US", "name": "English (American)", "features": ["tag_handling", "glossary_id"] }
+]
+```
+
+
+## Products list
The `product` query parameter identifies which DeepL API product you are querying language support for:
@@ -26,9 +98,9 @@ The `product` query parameter identifies which DeepL API product you are queryin
|---|---|
| `translate_text` | Text translation via the `/v2/translate` endpoint |
| `translate_document` | Document translation via the `/v2/document` endpoint |
-| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
| `voice` | Speech-to-speech/text via the `/v3/voice` endpoints |
| `write` | Text improvement via the `/v2/write` endpoints |
+| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
`glossary` appears both as a standalone product name and as a feature value on individual languages for other products (e.g. `voice`). As a feature, it indicates that the language supports use with a glossary for that product.
@@ -67,172 +139,6 @@ Feature values are defined as follows:
- **`writing_style`**: The language supports writing style selection
- **`tone`**: The language supports tone selection
-
-
-
-The example below uses 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.
-
-
- The example responses below have been shortened for clarity. The actual API response includes all supported languages.
-
-
-```sh Example request: All source languages
-curl -X GET 'https://api.deepl.com/v3/languages/source' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example response
-[
- {
- "code": "de",
- "name": "German",
- "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
- },
- {
- "code": "en",
- "name": "English",
- "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
- }
-]
-```
-
-```sh Example request: Source languages for text translation (with features)
-curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example response
-[
- {
- "code": "de",
- "name": "German",
- "features": ["tag_handling", "glossary_id"]
- },
- {
- "code": "en",
- "name": "English",
- "features": ["tag_handling", "glossary_id"]
- }
-]
-```
-
-```sh Example request: All target languages
-curl -X GET 'https://api.deepl.com/v3/languages/target' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example response
-[
- {
- "code": "en-US",
- "name": "English (American)",
- "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
- },
- {
- "code": "fr",
- "name": "French",
- "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
- }
-]
-```
-
-```sh Example request: Target languages for text translation (with features)
-curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example response
-[
- {
- "code": "de",
- "name": "German",
- "features": ["formality", "tag_handling", "glossary_id"]
- },
- {
- "code": "en-US",
- "name": "English (American)",
- "features": ["tag_handling", "glossary_id"]
- },
- {
- "code": "fr",
- "name": "French",
- "features": ["formality", "tag_handling", "glossary_id"]
- }
-]
-```
-
-```sh Example request: Filter target languages by source
-curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&source_lang=de' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example response
-[
- {
- "code": "en-US",
- "name": "English (American)",
- "features": ["tag_handling", "glossary_id"]
- },
- {
- "code": "fr",
- "name": "French",
- "features": ["formality", "tag_handling", "glossary_id"]
- }
-]
-```
-
-
-
-
- The example responses below have been shortened for clarity. The actual API response includes all supported languages.
-
-
-```http Example request: All source languages
-GET /v3/languages/source HTTP/2
-Host: api.deepl.com
-Authorization: DeepL-Auth-Key [yourAuthKey]
-User-Agent: YourApp/1.2.3
-```
-
-```json Example response
-[
- {
- "code": "de",
- "name": "German",
- "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
- },
- {
- "code": "fr",
- "name": "French",
- "products": ["translate_text", "translate_document", "glossary", "voice", "write"]
- }
-]
-```
-
-```http Example request: Target languages for document translation
-GET /v3/languages/target?product=translate_document HTTP/2
-Host: api.deepl.com
-Authorization: DeepL-Auth-Key [yourAuthKey]
-User-Agent: YourApp/1.2.3
-```
-
-```json Example response
-[
- {
- "code": "en-GB",
- "name": "English (British)",
- "features": ["glossary_id"]
- },
- {
- "code": "es",
- "name": "Spanish",
- "features": ["formality", "glossary_id"]
- }
-]
-```
-
-
-
## Response structure
Both endpoints return a flat JSON array of language objects. Each object contains:
From c60b15f1f2a02203bbb3f43f51abcdb837c57f64 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 24 Feb 2026 22:08:44 +0100
Subject: [PATCH 06/32] revert naming v2 languages legacy
---
api-reference/languages.mdx | 6 +++---
.../languages/retrieve-supported-languages.mdx | 2 +-
docs.json | 16 ++++++++--------
3 files changed, 12 insertions(+), 12 deletions(-)
diff --git a/api-reference/languages.mdx b/api-reference/languages.mdx
index a2889e9..70341d2 100644
--- a/api-reference/languages.mdx
+++ b/api-reference/languages.mdx
@@ -1,7 +1,7 @@
---
-title: "Retrieve languages (legacy)"
-sidebarTitle: "Overview (legacy)"
-description: "API reference for retrieving supported languages with the DeepL API using the v2 endpoint."
+title: "Retrieve languages"
+sidebarTitle: "Overview"
+description: "API reference for retrieving supported languages with the DeepL API."
---
Get all currently supported source and target languages that can be used for text and document translation.
diff --git a/api-reference/languages/retrieve-supported-languages.mdx b/api-reference/languages/retrieve-supported-languages.mdx
index 616bddb..4e04361 100644
--- a/api-reference/languages/retrieve-supported-languages.mdx
+++ b/api-reference/languages/retrieve-supported-languages.mdx
@@ -1,4 +1,4 @@
---
openapi: get /v2/languages
-title: "Retrieve supported languages (legacy)"
+title: "Retrieve supported languages"
---
diff --git a/docs.json b/docs.json
index b0c821d..fecdb62 100644
--- a/docs.json
+++ b/docs.json
@@ -191,18 +191,18 @@
},
{
"group": "Retrieve languages",
+ "pages": [
+ "api-reference/languages",
+ "api-reference/languages/retrieve-supported-languages"
+ ]
+ },
+ {
+ "group": "Retrieve languages [BETA]",
"pages": [
"api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
"api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta",
"api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta",
- "api-reference/api-reference/retrieve-languages/migrate-from-v2-languages",
- {
- "group": "v2 (Legacy)",
- "pages": [
- "api-reference/languages",
- "api-reference/languages/retrieve-supported-languages"
- ]
- }
+ "api-reference/api-reference/retrieve-languages/migrate-from-v2-languages"
]
},
{
From 9719d74166ae09affb79ab181ad9ae799e2cb593 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 24 Feb 2026 22:29:52 +0100
Subject: [PATCH 07/32] rewrites and improvements
---
...ve-supported-languages-by-product-beta.mdx | 198 ++++++------------
1 file changed, 61 insertions(+), 137 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 45226bc..e8c25bc 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -27,9 +27,9 @@ To understand how we'll update these endpoints when we add translation support f
You can call the `/v3/languages/source` and endpoint to retrieve a list of all supported source languages, and the
`/v3/languages/target` endpoint to retrieve a list of all supported target languages.
-
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.
+
```sh Example request: supported source languages
@@ -46,20 +46,40 @@ Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
```
+
```json Example response
[
- { "code": "de", "name": "German", "products": ["translate_text", "translate_document", "glossary", "voice", "write"] },
- { "code": "en", "name": "English", "products": ["translate_text", "translate_document", "glossary", "voice", "write"] }
+ {
+ "code": "de",
+ "name": "German",
+ "products": [
+ "translate_text",
+ "translate_document",
+ "glossary",
+ "voice",
+ "write"
+ ]
+ },
+ {
+ "code": "en",
+ "name": "English",
+ "products": [
+ "translate_text",
+ "translate_document",
+ "glossary",
+ "voice",
+ "write"
+ ]
+ }
]
```
-
-
## Filtering by product
-When the `product` query parameter is specified, only languages supporting that product are returned.
-Additionally, the `products` array is replaced by a `features` array indicating which product-specific capabilities that
+You may also specify the `product` query parameter as a filter, so only languages supporting that product are returned.
+In this case the `products` array is omitted from each language.
+Additionally, languages may include a `features` array indicating which product-specific capabilities the
language supports:
@@ -81,14 +101,29 @@ User-Agent: YourApp/1.2.3
```
+
```json Example response
[
- { "code": "de", "name": "German", "features": ["formality", "tag_handling", "glossary_id"] },
- { "code": "en-US", "name": "English (American)", "features": ["tag_handling", "glossary_id"] }
+ {
+ "code": "de",
+ "name": "German",
+ "features": [
+ "formality",
+ "tag_handling",
+ "glossary_id"
+ ]
+ },
+ {
+ "code": "en-US",
+ "name": "English (American)",
+ "features": [
+ "tag_handling",
+ "glossary_id"
+ ]
+ }
]
```
-
## Products list
@@ -98,17 +133,22 @@ The `product` query parameter identifies which DeepL API product you are queryin
|---|---|
| `translate_text` | Text translation via the `/v2/translate` endpoint |
| `translate_document` | Document translation via the `/v2/document` endpoint |
-| `voice` | Speech-to-speech/text via the `/v3/voice` endpoints |
+| `voice` | Speech-to-text and speech-to-speech via the `/v3/voice` endpoints |
| `write` | Text improvement via the `/v2/write` endpoints |
| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
- `glossary` appears both as a standalone product name and as a feature value on individual languages for other products (e.g. `voice`). As a feature, it indicates that the language supports use with a glossary for that product.
+ `glossary` is a product value indicating glossary management support.
+ Support for glossaries within specific products (for example text translation) is indicated by the `glossary_id`
+ feature value, explained in the following section.
+As we add new products to the DeepL API, the `products` list for each language will be extended.
+
## Product features
-When a `product` query parameter is specified, language objects may include a `features` array. The features that can appear depend on both the product and whether the language is a source or target language.
+When the `product` query parameter is specified, language objects may include a `features` array.
+The features indicate which optional endpoint parameters are supported for that language.
### Source language features
@@ -139,137 +179,21 @@ Feature values are defined as follows:
- **`writing_style`**: The language supports writing style selection
- **`tone`**: The language supports tone selection
-## Response structure
-
-Both endpoints return a flat JSON array of language objects. Each object contains:
-
-- **`code`**: The language code used in API requests (e.g., `"de"`, `"en"`, `"fr"`)
-- **`name`**: The English name of the language (e.g., `"German"`, `"English"`, `"French"`)
-- **`products`** *(optional)*: An array of product identifiers indicating which products support this language. Only present when no `product` query parameter is specified.
-- **`features`** *(optional)*: An array of feature strings indicating additional capabilities for this language with the specified product. Only present when a `product` query parameter is specified and the language supports one or more features for that product.
-
-### Source vs target language codes
-
-Source languages use base codes (e.g., `"en"`), while target languages may use regional variant codes (e.g., `"en-US"`, `"en-GB"`):
-
-```javascript
-// Source language
-{ "code": "en", "name": "English" }
-
-// Target languages
-{ "code": "en-US", "name": "English (American)" }
-{ "code": "en-GB", "name": "English (British)" }
-```
-
-## Query parameters
-
-### GET /v3/languages/source
-
-
- Filter languages by product. Supported values: `translate_text`, `translate_document`, `glossary`, `voice`, `write`.
-
- When specified:
- - Only languages supporting that product are returned
- - The `products` field is omitted from the response
- - Source languages may include a `features` array for product-specific capabilities
-
-
-
- Filter source languages to those compatible with a specific target language. Must be used together with `product`. Cannot be used together with `source_lang`.
-
- - Language code must be valid (e.g., `"en"`, `"en-US"`, `"fr"`)
- - Only returns source languages that form a supported language pair with the given target
-
-
-### GET /v3/languages/target
-
-
- Filter languages by product. Supported values: `translate_text`, `translate_document`, `glossary`, `voice`, `write`.
-
- When specified:
- - Only languages supporting that product are returned
- - The `products` field is omitted from the response
- - Target languages may include a `features` array for product-specific capabilities
-
-
-
- Filter target languages to those compatible with a specific source language. Must be used together with `product`. Cannot be used together with `target_lang`.
-
- - Language code must be valid (e.g., `"de"`, `"en"`, `"fr"`)
- - Only returns target languages that form a supported language pair with the given source
-
## Language pair exceptions
-Some products may support individual languages but not every combination. For example, a voice product might support `de→en` and `fr→en`, but not `de→fr`. When querying with a language filter, unsupported pairs are automatically excluded:
-
-```javascript
-GET /v3/languages/target?product=voice&source_lang=de
-// Returns valid target languages for de, excluding any that de cannot be paired with
-```
-
-## Use cases
-
-### Building a translation UI
-
-```javascript
-// Fetch source and target languages for text translation
-const [sourceRes, targetRes] = await Promise.all([
- fetch('https://api.deepl.com/v3/languages/source?product=translate_text', {
- headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
- }),
- fetch('https://api.deepl.com/v3/languages/target?product=translate_text', {
- headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' }
- })
-]);
-const sources = await sourceRes.json();
-const targets = await targetRes.json();
-```
-
-### Checking feature support
-
-```javascript
-// Find target languages that support formality for text translation
-const response = await fetch(
- 'https://api.deepl.com/v3/languages/target?product=translate_text',
- { headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' } }
-);
-const targets = await response.json();
-
-const formalityTargets = targets
- .filter(lang => lang.features?.includes('formality'))
- .map(lang => lang.code);
-// Example result: ["de", "es", "fr", "it", "ja", "nl", "pl", "pt-BR", "pt-PT", "ru"]
-```
-
-### Validating a language pair
-
-```javascript
-// Check which targets are valid when source is de for voice
-const response = await fetch(
- 'https://api.deepl.com/v3/languages/target?product=voice&source_lang=de',
- { headers: { 'Authorization': 'DeepL-Auth-Key [yourAuthKey]' } }
-);
-const targets = await response.json();
-const isFrenchSupported = targets.some(lang => lang.code === 'fr');
-```
+In rare cases, feature support for a language pair may differ from that predicted by the feature support for the source
+and target languages individually. This sometimes occurs due to language-specifics of DeepL's AI models.
-## Error responses
+A hypothetical example: text translation formality is supported for source language Ukrainian, and it is also supported
+for target language Russian. However, translating specifically from Ukrainian to Russian does not support formality.
-
- Invalid query parameters:
- - Unknown `product` value
- - `source_lang` or `target_lang` used without `product`
- - Invalid language code
-
+It is complex to handle these cases, so we design our API endpoints to perform the best possible function in such cases,
+for example, by ignoring formality support in the Ukrainian to Russian case above. However, we recognize some of our
+users are interested in these specifics, so this section explains how to retrieve this information.
-
- Missing or invalid authentication.
-
+TODO
-
- API key doesn't have access to this endpoint.
-
## API stability
From 7c3ff28438726ed041f73bf8b32828902103fd4f Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 10:18:59 +0100
Subject: [PATCH 08/32] rewrites and improvements
---
...ve-supported-languages-by-product-beta.mdx | 54 +++++++------------
1 file changed, 18 insertions(+), 36 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index e8c25bc..85ef9a5 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -4,8 +4,7 @@ sidebarTitle: 'Overview'
description: "API reference for retrieving supported languages with the DeepL API across all products."
---
-Get information about all currently supported source and target languages across all DeepL API products, including
-text translation, document translation, glossaries, DeepL Voice, and DeepL Write.
+Get information about all currently supported source and target languages across all DeepL API products.
The `/v3/languages` endpoints provide a single source of truth for language and feature support across all DeepL
@@ -24,10 +23,11 @@ To understand how we'll update these endpoints when we add translation support f
## Basic example
-You can call the `/v3/languages/source` and endpoint to retrieve a list of all supported source languages, and the
-`/v3/languages/target` endpoint to retrieve a list of all supported target languages.
+You can call the `/v3/languages/source` and `/v3/languages/target` endpoints to retrieve a list of all supported
+source and target languages.
-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.
+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.
@@ -48,6 +48,8 @@ User-Agent: YourApp/1.2.3
+The example responses are truncated; the full API response includes over 100 languages.
+
```json Example response
[
{
@@ -79,7 +81,8 @@ User-Agent: YourApp/1.2.3
You may also specify the `product` query parameter as a filter, so only languages supporting that product are returned.
In this case the `products` array is omitted from each language.
-Additionally, languages may include a `features` array indicating which product-specific capabilities the
+
+Additionally, each language may include a `features` array indicating which product-specific capabilities the
language supports:
@@ -139,46 +142,25 @@ The `product` query parameter identifies which DeepL API product you are queryin
`glossary` is a product value indicating glossary management support.
+
Support for glossaries within specific products (for example text translation) is indicated by the `glossary_id`
feature value, explained in the following section.
-As we add new products to the DeepL API, the `products` list for each language will be extended.
+As we add new products to the DeepL API, the `products` list for each supported language will be extended.
## Product features
-When the `product` query parameter is specified, language objects may include a `features` array.
-The features indicate which optional endpoint parameters are supported for that language.
-
-### Source language features
-
-| Product | Feature |
-|---|---|
-| `translate_text` | `tag_handling`, `glossary_id` |
-| `translate_document` | `glossary_id` |
-| `glossary` | *(none)* |
-| `voice` | `glossary_id` |
-| `write` | *(none)* |
-
-### Target language features
-
-| Product | Feature |
-|---|---|
-| `translate_text` | `formality`, `tag_handling`, `glossary_id`, `custom_instructions` |
-| `translate_document` | `formality`, `glossary_id` |
-| `glossary` | *(none)* |
-| `voice` | `formality`, `glossary_id` |
-| `write` | `writing_style`, `tone` |
+As described earlier, when the `product` query parameter is specified, language objects may include a `features` array.
+The included features indicate which optional endpoint parameters are supported for that language.
-Feature values are defined as follows:
+For example, `["tag_handling", "glossary_id"]` for English (American) above indicates that when this language is used
+as the target language for text translation, the `tag_handling` and `glossary_id` parameters are supported.
-- **`formality`**: The language supports formality control (formal/informal)
-- **`tag_handling`**: The language supports XML/HTML tag handling in translation requests
-- **`glossary_id`**: The language supports use with a glossary (via `glossary_id` parameter)
-- **`custom_instructions`**: The language supports custom translation instructions
-- **`writing_style`**: The language supports writing style selection
-- **`tone`**: The language supports tone selection
+Features need to be included in both the source and target language's `features` array to be supported.
+API endpoints describe in their documentation which request parameters are language-dependent, and indicate the
+feature values to check for in the `features` array.
## Language pair exceptions
From d5f1175c5e4e0c221ae456ed013de9c95c679f5f Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 10:40:24 +0100
Subject: [PATCH 09/32] rewrites and improvements
---
...ve-supported-languages-by-product-beta.mdx | 41 +++++++++++--------
1 file changed, 25 insertions(+), 16 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 85ef9a5..ff6bade 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -23,8 +23,8 @@ To understand how we'll update these endpoints when we add translation support f
## Basic example
-You can call the `/v3/languages/source` and `/v3/languages/target` endpoints to retrieve a list of all supported
-source and target languages.
+You can call the `/v3/languages/source` endpoint to retrieve a list of all supported source languages,
+and call the `/v3/languages/target` endpoint to retrieve a list of all supported target languages.
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.
@@ -48,7 +48,7 @@ User-Agent: YourApp/1.2.3
-The example responses are truncated; the full API response includes over 100 languages.
+The following example response is truncated; the full API response includes over 100 languages.
```json Example response
[
@@ -79,11 +79,11 @@ The example responses are truncated; the full API response includes over 100 lan
## Filtering by product
-You may also specify the `product` query parameter as a filter, so only languages supporting that product are returned.
-In this case the `products` array is omitted from each language.
+You may also specify the `product` query parameter as a filter, to return only languages supporting that product.
+The `products` array is also omitted from each language.
-Additionally, each language may include a `features` array indicating which product-specific capabilities the
-language supports:
+Instead, each language may include a `features` array indicating which product-specific capabilities are supported for
+the language:
@@ -141,7 +141,7 @@ The `product` query parameter identifies which DeepL API product you are queryin
| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
- `glossary` is a product value indicating glossary management support.
+ `glossary` is a product value indicating glossaries can be created for that language.
Support for glossaries within specific products (for example text translation) is indicated by the `glossary_id`
feature value, explained in the following section.
@@ -154,10 +154,12 @@ As we add new products to the DeepL API, the `products` list for each supported
As described earlier, when the `product` query parameter is specified, language objects may include a `features` array.
The included features indicate which optional endpoint parameters are supported for that language.
-For example, `["tag_handling", "glossary_id"]` for English (American) above indicates that when this language is used
-as the target language for text translation, the `tag_handling` and `glossary_id` parameters are supported.
+For example, `["formality", "tag_handling", "glossary_id"]` for German above indicates that when this language is used
+as the target language for text translation, the `formality`, `tag_handling` and `glossary_id` parameters are supported.
-Features need to be included in both the source and target language's `features` array to be supported.
+Features must be included in both the source and target language's `features` array to be supported. For example, if
+the source language French (`fr`) includes `"formality"` for text translation, but the target language Greek (`el`) does
+not, then text translations from French to Greek are possible but will not support formality.
API endpoints describe in their documentation which request parameters are language-dependent, and indicate the
feature values to check for in the `features` array.
@@ -171,11 +173,18 @@ A hypothetical example: text translation formality is supported for source langu
for target language Russian. However, translating specifically from Ukrainian to Russian does not support formality.
It is complex to handle these cases, so we design our API endpoints to perform the best possible function in such cases,
-for example, by ignoring formality support in the Ukrainian to Russian case above. However, we recognize some of our
-users are interested in these specifics, so this section explains how to retrieve this information.
-
-TODO
-
+for example, by ignoring formality support in the Ukrainian to Russian case above. However, in some cases this
+information may be, so this section explains how to retrieve it.
+
+### `source_lang` and `target_lang` query parameters
+
+You may also specify a `source_lang` or `target_lang` query parameter in addition to the `product` query parameter:
+- for `/v3/languages/source`, the `target_lang` parameter indicates the target language for which you want to retrieve
+language support
+- for `/v3/languages/target`, the `source_lang` parameter indicates the source language for which you want to retrieve
+language support
+These parameters will modify the feature support information returned for each language, applying any of these
+exceptional cases as described above.
## API stability
From 3c88b7a360e998d5a9f02664af868603eb7ea473 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 10:50:13 +0100
Subject: [PATCH 10/32] rewrites and improvements
---
.../migrate-from-v2-languages.mdx | 24 ++++++++++-
...ve-supported-languages-by-product-beta.mdx | 40 ++++++++++++++++++-
2 files changed, 61 insertions(+), 3 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index b4bd2f8..cc0b8ee 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -47,7 +47,29 @@ v2 target languages include a boolean `supports_formality` field. v3 replaces th
| v2 field | v3 equivalent |
|---|---|
-| `"supports_formality": true` | `"features": ["formality"]` on target language (when `product` is specified) |
+| `"supports_formality": true` | `"features": ["formality"]` on both source and target language (when `product` is specified) |
+
+For example, querying target languages for text translation:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (truncated)
+[
+ {
+ "code": "de",
+ "name": "German",
+ "features": ["formality", "tag_handling", "glossary_id"]
+ },
+ {
+ "code": "en-US",
+ "name": "English (American)",
+ "features": ["tag_handling", "glossary_id"]
+ }
+]
+```
The `features` array only appears on a language object when a `product` parameter is specified and the language supports at least one feature for that product. See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta) for the full list of features per product.
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index ff6bade..c005f5f 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -80,9 +80,9 @@ The following example response is truncated; the full API response includes over
## Filtering by product
You may also specify the `product` query parameter as a filter, to return only languages supporting that product.
-The `products` array is also omitted from each language.
+In this case the `products` array is no longer included in the response.
-Instead, each language may include a `features` array indicating which product-specific capabilities are supported for
+Instead, each language includes a `features` array indicating which product-specific capabilities are supported for
the language:
@@ -186,6 +186,42 @@ language support
These parameters will modify the feature support information returned for each language, applying any of these
exceptional cases as described above.
+Continuing the hypothetical Ukrainian to Russian example: querying target languages for text translation without a
+source filter shows Russian with `formality` support, since Russian generally supports formality as a target language:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (truncated)
+[
+ {
+ "code": "ru",
+ "name": "Russian",
+ "features": ["formality", "tag_handling", "glossary_id"]
+ }
+]
+```
+
+Specifying `source_lang=uk` applies the language-pair exception, and Russian is returned without `formality` indicating
+the exception:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&source_lang=uk' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (truncated)
+[
+ {
+ "code": "ru",
+ "name": "Russian",
+ "features": ["tag_handling", "glossary_id"]
+ }
+]
+```
+
## API stability
The v3 language endpoints are designed to be forward-compatible:
From 789ac7697757442c4d1ceab25bd75a9f24f060bd Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 10:52:44 +0100
Subject: [PATCH 11/32] page title
---
docs.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs.json b/docs.json
index fecdb62..5628501 100644
--- a/docs.json
+++ b/docs.json
@@ -197,7 +197,7 @@
]
},
{
- "group": "Retrieve languages [BETA]",
+ "group": "Retrieve languages by product [BETA]",
"pages": [
"api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
"api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta",
From f2b6cee50cc0ac94c194b1432705208f3713a526 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 10:58:10 +0100
Subject: [PATCH 12/32] whitespace
---
api-reference/openapi.yaml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index d3411d4..7c54cb4 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -272,7 +272,7 @@ paths:
- key_id
properties:
key_id:
- $ref: '#/components/schemas/ApiKeyId'
+ $ref: '#/components/schemas/ApiKeyId'
responses:
200:
description: The deactivate function returns a JSON representation of the deactivated API key.
@@ -3957,7 +3957,7 @@ components:
- ja
- ko
- zh
- StyleRuleName:
+ StyleRuleName:
description: Name associated with the style rule.
type: string
DocumentTranslationError:
@@ -4253,7 +4253,7 @@ components:
description: |-
When true, the response will include the billed_characters parameter, giving the
number of characters from the request that will be counted by DeepL for billing purposes.
- type: boolean
+ type: boolean
SplitSentencesOption:
description: |-
Sets whether the translation engine should first split the input into sentences.
@@ -4261,7 +4261,7 @@ components:
Possible values are:
* 0 - no splitting at all, whole input is treated as one sentence
* 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines
- * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines
+ * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines
type: string
enum:
- '0'
@@ -4407,7 +4407,7 @@ components:
Sets which version of the tag handling algorithm should be used. Options currently available:
* `v1`: Traditional algorithm (currently the default, will become deprecated in the future).
* `v2`: Improved algorithm released in October 2025 (will become the default in the future).
-
+
type: string
enum:
- v1
From 53a433dea8d6535c779daff5c3bfbf6ffae60432 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 10:58:58 +0100
Subject: [PATCH 13/32] add summary of example
---
.../retrieve-languages/migrate-from-v2-languages.mdx | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index cc0b8ee..54f987a 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -71,7 +71,9 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
]
```
-The `features` array only appears on a language object when a `product` parameter is specified and the language supports at least one feature for that product. See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta) for the full list of features per product.
+The response indicates German supports `formality`, but English (American) does not.
+
+The `features` array only appears on a language object when a `product` parameter is specified. See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta) for the full list of features per product.
### Flat array response
From 97343484d29f9433f43bb6c5369f32a55fb17542 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 11:10:53 +0100
Subject: [PATCH 14/32] add exceptions endpoint, better wording
---
...ve-supported-languages-by-product-beta.mdx | 80 +++++++++++++++++--
1 file changed, 72 insertions(+), 8 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index c005f5f..54b5bce 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -166,15 +166,15 @@ feature values to check for in the `features` array.
## Language pair exceptions
-In rare cases, feature support for a language pair may differ from that predicted by the feature support for the source
-and target languages individually. This sometimes occurs due to language-specifics of DeepL's AI models.
+In rare cases, feature support for a specific language pair may differ from the feature support returned for the source
+and target languages individually. This occurs due to intricacies and language-specifics of DeepL's AI models.
A hypothetical example: text translation formality is supported for source language Ukrainian, and it is also supported
-for target language Russian. However, translating specifically from Ukrainian to Russian does not support formality.
+for target language Russian. However, translating specifically from Ukrainian to Russian does *not* support formality.
It is complex to handle these cases, so we design our API endpoints to perform the best possible function in such cases,
-for example, by ignoring formality support in the Ukrainian to Russian case above. However, in some cases this
-information may be, so this section explains how to retrieve it.
+for example, by continuing with the request and ignoring formality support in the case above. However, in some cases
+information about these exceptions may be useful, so this section explains how to retrieve it.
### `source_lang` and `target_lang` query parameters
@@ -194,7 +194,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
-```json Example response (truncated)
+```json Example target languages response (truncated)
[
{
"code": "ru",
@@ -204,7 +204,25 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
]
```
-Specifying `source_lang=uk` applies the language-pair exception, and Russian is returned without `formality` indicating
+Similarly, querying source languages for text translation without a target filter shows Ukrainian with `formality`
+support, since Ukrainian generally supports formality as a source language:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example source languages response (truncated)
+[
+ {
+ "code": "uk",
+ "name": "Ukrainian",
+ "features": ["formality", "tag_handling", "glossary_id"]
+ }
+]
+```
+
+However, specifying `source_lang=uk` applies the language-pair exception, and Russian is returned without `formality` indicating
the exception:
```sh
@@ -212,7 +230,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&so
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
-```json Example response (truncated)
+```json Example target languages response, filtering for source_lang=uk (truncated)
[
{
"code": "ru",
@@ -222,6 +240,52 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&so
]
```
+Similarly, querying source languages while specifying `target_lang=ru` applies the language-pair exception, and
+Ukrainian is returned without `formality` indicating the exception:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text&target_lang=ru' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example source languages response, filtering for target_lang=ru (truncated)
+[
+ {
+ "code": "uk",
+ "name": "Ukrainian",
+ "features": ["tag_handling", "glossary_id"]
+ }
+]
+```
+
+### Retrieving language pair exceptions directly
+
+Language pair exceptions are also available directly via the `/v3/languages/exceptions` endpoint. The `product` query
+parameter is required to specify the product for which you want to retrieve exceptions.
+
+The response includes a list of language pairs for which exceptions exist, with their actual feature support.
+
+Continuing the hypothetical example, querying exceptions for text translation shows that Ukrainian-Russian does not
+support formality:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/exceptions?product=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example exceptions response (truncated)
+[
+ {
+ "source_lang": "uk",
+ "target_lang": "ru",
+ "features": ["tag_handling", "glossary_id"]
+ }
+]
+```
+
+You can apply these exceptions in client logic, overriding the responses from the `/v3/languages/source` and
+`/v3/languages/target` endpoints.
+
## API stability
The v3 language endpoints are designed to be forward-compatible:
From b8bfd8bb148bdcf5543ae317f398236ad35ed5e0 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 11:17:50 +0100
Subject: [PATCH 15/32] openapi for exceptions endpoint
---
...retrieve-language-pair-exceptions-beta.mdx | 4 +
...ve-supported-languages-by-product-beta.mdx | 1 +
api-reference/openapi.yaml | 80 +++++++++++++++++++
docs.json | 1 +
4 files changed, 86 insertions(+)
create mode 100644 api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta.mdx
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta.mdx
new file mode 100644
index 0000000..41b56a8
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages/exceptions
+title: "Retrieve language pair exceptions [BETA]"
+---
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 54b5bce..804cf32 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -18,6 +18,7 @@ Get information about all currently supported source and target languages across
We also provide specs that are auto-generated from DeepL's OpenAPI file. You can find them here:
- [Retrieve source languages](/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta)
- [Retrieve target languages](/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta)
+- [Retrieve language pair exceptions](/api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta)
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/openapi.yaml b/api-reference/openapi.yaml
index 7c54cb4..5dade33 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -2238,6 +2238,86 @@ paths:
$ref: '#/components/responses/ServiceUnavailable'
security:
- auth_header: []
+ /v3/languages/exceptions:
+ get:
+ tags:
+ - MetaInformation
+ summary: Retrieve Language Pair Exceptions
+ operationId: getLanguagePairExceptions
+ description: |-
+ Returns language pairs for which feature support differs from what would be predicted by the
+ feature support of the source and target languages individually.
+
+ The `product` parameter is required. Results are specific to the product, as exceptions may
+ vary across products.
+ parameters:
+ - name: product
+ in: query
+ required: true
+ schema:
+ type: string
+ enum:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ description: The product for which to retrieve language pair exceptions. Required.
+ responses:
+ 200:
+ description: JSON array where each item represents a language pair with exceptional feature support.
+ headers:
+ X-Trace-ID:
+ $ref: '#/components/headers/X-Trace-ID'
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ required:
+ - source_lang
+ - target_lang
+ - features
+ properties:
+ source_lang:
+ description: The source language code of the language pair.
+ type: string
+ example: uk
+ target_lang:
+ description: The target language code of the language pair.
+ type: string
+ example: ru
+ features:
+ description: |-
+ The actual features supported for this specific language pair, which differs
+ from the features reported for the source or target language individually.
+ type: array
+ items:
+ type: string
+ example:
+ - tag_handling
+ - glossary_id
+ example:
+ - source_lang: uk
+ target_lang: ru
+ features:
+ - tag_handling
+ - glossary_id
+ 400:
+ $ref: '#/components/responses/BadRequest'
+ 401:
+ $ref: '#/components/responses/Unauthorized'
+ 403:
+ $ref: '#/components/responses/Forbidden'
+ 429:
+ $ref: '#/components/responses/TooManyRequests'
+ 500:
+ $ref: '#/components/responses/InternalServerError'
+ 503:
+ $ref: '#/components/responses/ServiceUnavailable'
+ security:
+ - auth_header: []
/v3/style_rules:
get:
summary: Retrieve style rule lists
diff --git a/docs.json b/docs.json
index 5628501..ea84e60 100644
--- a/docs.json
+++ b/docs.json
@@ -202,6 +202,7 @@
"api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
"api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta",
"api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta",
+ "api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta",
"api-reference/api-reference/retrieve-languages/migrate-from-v2-languages"
]
},
From 7e2879ba66ccc0540587b7bdece738ffae6e6dfc Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 11:24:53 +0100
Subject: [PATCH 16/32] rewording
---
.../retrieve-supported-languages-by-product-beta.mdx | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 804cf32..ac81ab1 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -142,7 +142,8 @@ The `product` query parameter identifies which DeepL API product you are queryin
| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
- `glossary` is a product value indicating glossaries can be created for that language.
+ `glossary` is a product 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_id`
feature value, explained in the following section.
@@ -173,9 +174,9 @@ and target languages individually. This occurs due to intricacies and language-s
A hypothetical example: text translation formality is supported for source language Ukrainian, and it is also supported
for target language Russian. However, translating specifically from Ukrainian to Russian does *not* support formality.
-It is complex to handle these cases, so we design our API endpoints to perform the best possible function in such cases,
-for example, by continuing with the request and ignoring formality support in the case above. However, in some cases
-information about these exceptions may be useful, so this section explains how to retrieve it.
+It is complex to handle these cases, so we design our API endpoints to perform the "best effort" in such cases. For
+example, by ignoring formality support and continuing with the translation rather than failing the request.
+However, in some cases information about these exceptions may be useful, so this section explains how to retrieve it.
### `source_lang` and `target_lang` query parameters
@@ -285,7 +286,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/exceptions?product=translate_tex
```
You can apply these exceptions in client logic, overriding the responses from the `/v3/languages/source` and
-`/v3/languages/target` endpoints.
+`/v3/languages/target` endpoints for those specific language pairs.
## API stability
From 3e1ca97dac485c456c4e1032bf735574369fe7f2 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 11:28:59 +0100
Subject: [PATCH 17/32] rewording
---
.../retrieve-supported-languages-by-product-beta.mdx | 11 ++++++-----
1 file changed, 6 insertions(+), 5 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index ac81ab1..3d144bf 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -80,11 +80,12 @@ The following example response is truncated; the full API response includes over
## Filtering by product
-You may also specify the `product` query parameter as a filter, to return only languages supporting that product.
+For the `/v3/languages/source` and `/v3/languages/target` endpoints you may also specify the `product` query parameter
+as a filter, to return only source or target languages supporting that product.
In this case the `products` array is no longer included in the response.
-Instead, each language includes a `features` array indicating which product-specific capabilities are supported for
-the language:
+Instead, each source or target language includes a `features` array indicating which product-specific capabilities are
+supported for the language:
@@ -154,12 +155,12 @@ As we add new products to the DeepL API, the `products` list for each supported
## Product features
As described earlier, when the `product` query parameter is specified, language objects may include a `features` array.
-The included features indicate which optional endpoint parameters are supported for that language.
+The included features indicate which optional parameters are supported for that language.
For example, `["formality", "tag_handling", "glossary_id"]` for German above indicates that when this language is used
as the target language for text translation, the `formality`, `tag_handling` and `glossary_id` parameters are supported.
-Features must be included in both the source and target language's `features` array to be supported. For example, if
+Features must be included in *both* the source and target language's `features` array to be supported. For example, if
the source language French (`fr`) includes `"formality"` for text translation, but the target language Greek (`el`) does
not, then text translations from French to Greek are possible but will not support formality.
From 3e2fdad98d854ee590f1fd93a9faa3a964ce505e Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 11:36:36 +0100
Subject: [PATCH 18/32] remove old "glossary" feature
---
api-reference/openapi.yaml | 2 --
1 file changed, 2 deletions(-)
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index 5dade33..8c92fe4 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -2033,7 +2033,6 @@ paths:
enum:
- tag_handling
- glossary_id
- - glossary
example:
- tag_handling
- glossary_id
@@ -2177,7 +2176,6 @@ paths:
- tag_handling
- glossary_id
- custom_instructions
- - glossary
- writing_style
- tone
example:
From f71f46581d8f3a330c6299354695915f82b14c83 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 25 Feb 2026 13:24:30 +0100
Subject: [PATCH 19/32] change "code" to "lang" for consistency
---
.../migrate-from-v2-languages.mdx | 6 ++---
...ve-supported-languages-by-product-beta.mdx | 16 ++++++------
api-reference/openapi.yaml | 26 +++++++++----------
3 files changed, 24 insertions(+), 24 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index 54f987a..cb2bfaa 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -59,12 +59,12 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
```json Example response (truncated)
[
{
- "code": "de",
+ "lang": "de",
"name": "German",
"features": ["formality", "tag_handling", "glossary_id"]
},
{
- "code": "en-US",
+ "lang": "en-US",
"name": "English (American)",
"features": ["tag_handling", "glossary_id"]
}
@@ -83,7 +83,7 @@ v2 returns a flat JSON array. v3 also returns a flat array — but each endpoint
| v2 field | v3 field |
|---|---|
-| `language` | `code` |
+| `language` | `lang` |
| `name` | `name` *(unchanged)* |
| `supports_formality` | `features` *(array, product-specific)* |
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 3d144bf..ac1cf31 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -54,7 +54,7 @@ The following example response is truncated; the full API response includes over
```json Example response
[
{
- "code": "de",
+ "lang": "de",
"name": "German",
"products": [
"translate_text",
@@ -65,7 +65,7 @@ The following example response is truncated; the full API response includes over
]
},
{
- "code": "en",
+ "lang": "en",
"name": "English",
"products": [
"translate_text",
@@ -111,7 +111,7 @@ User-Agent: YourApp/1.2.3
```json Example response
[
{
- "code": "de",
+ "lang": "de",
"name": "German",
"features": [
"formality",
@@ -120,7 +120,7 @@ User-Agent: YourApp/1.2.3
]
},
{
- "code": "en-US",
+ "lang": "en-US",
"name": "English (American)",
"features": [
"tag_handling",
@@ -200,7 +200,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
```json Example target languages response (truncated)
[
{
- "code": "ru",
+ "lang": "ru",
"name": "Russian",
"features": ["formality", "tag_handling", "glossary_id"]
}
@@ -218,7 +218,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
```json Example source languages response (truncated)
[
{
- "code": "uk",
+ "lang": "uk",
"name": "Ukrainian",
"features": ["formality", "tag_handling", "glossary_id"]
}
@@ -236,7 +236,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&so
```json Example target languages response, filtering for source_lang=uk (truncated)
[
{
- "code": "ru",
+ "lang": "ru",
"name": "Russian",
"features": ["tag_handling", "glossary_id"]
}
@@ -254,7 +254,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text&ta
```json Example source languages response, filtering for target_lang=ru (truncated)
[
{
- "code": "uk",
+ "lang": "uk",
"name": "Ukrainian",
"features": ["tag_handling", "glossary_id"]
}
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index 8c92fe4..78a8ab1 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -1992,10 +1992,10 @@ paths:
items:
type: object
required:
- - code
+ - lang
- name
properties:
- code:
+ lang:
description: The language code of the given language.
type: string
example: de
@@ -2040,7 +2040,7 @@ paths:
allSourceLanguages:
summary: All source languages (no product filter)
value:
- - code: de
+ - lang: de
name: German
products:
- translate_text
@@ -2048,7 +2048,7 @@ paths:
- glossary
- voice
- write
- - code: en
+ - lang: en
name: English
products:
- translate_text
@@ -2059,12 +2059,12 @@ paths:
translateTextSources:
summary: Source languages for text translation
value:
- - code: de
+ - lang: de
name: German
features:
- tag_handling
- glossary_id
- - code: en
+ - lang: en
name: English
features:
- tag_handling
@@ -2133,10 +2133,10 @@ paths:
items:
type: object
required:
- - code
+ - lang
- name
properties:
- code:
+ lang:
description: The language code of the given language.
type: string
example: en-US
@@ -2186,7 +2186,7 @@ paths:
allTargetLanguages:
summary: All target languages (no product filter)
value:
- - code: en-US
+ - lang: en-US
name: English (American)
products:
- translate_text
@@ -2194,7 +2194,7 @@ paths:
- glossary
- voice
- write
- - code: fr
+ - lang: fr
name: French
products:
- translate_text
@@ -2205,18 +2205,18 @@ paths:
translateTextTargets:
summary: Target languages for text translation
value:
- - code: de
+ - lang: de
name: German
features:
- formality
- tag_handling
- glossary_id
- - code: en-US
+ - lang: en-US
name: English (American)
features:
- tag_handling
- glossary_id
- - code: fr
+ - lang: fr
name: French
features:
- formality
From b0c1cbc46f684a99fe03cd3aea517fc93b97d690 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 10 Mar 2026 13:02:50 +0100
Subject: [PATCH 20/32] rename glossary_id to glossary
---
.../migrate-from-v2-languages.mdx | 4 ++--
...ve-supported-languages-by-product-beta.mdx | 20 ++++++++---------
api-reference/openapi.yaml | 22 +++++++++----------
3 files changed, 23 insertions(+), 23 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index cb2bfaa..6989ad8 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -61,12 +61,12 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
{
"lang": "de",
"name": "German",
- "features": ["formality", "tag_handling", "glossary_id"]
+ "features": ["formality", "tag_handling", "glossary"]
},
{
"lang": "en-US",
"name": "English (American)",
- "features": ["tag_handling", "glossary_id"]
+ "features": ["tag_handling", "glossary"]
}
]
```
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index ac1cf31..e63f591 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -116,7 +116,7 @@ User-Agent: YourApp/1.2.3
"features": [
"formality",
"tag_handling",
- "glossary_id"
+ "glossary"
]
},
{
@@ -124,7 +124,7 @@ User-Agent: YourApp/1.2.3
"name": "English (American)",
"features": [
"tag_handling",
- "glossary_id"
+ "glossary"
]
}
]
@@ -146,7 +146,7 @@ The `product` query parameter identifies which DeepL API product you are queryin
`glossary` is a product 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_id`
+ Support for glossaries within specific products (for example text translation) is indicated by the `glossary`
feature value, explained in the following section.
@@ -157,8 +157,8 @@ As we add new products to the DeepL API, the `products` list for each supported
As described earlier, when the `product` query parameter is specified, language objects may include a `features` array.
The included features indicate which optional parameters are supported for that language.
-For example, `["formality", "tag_handling", "glossary_id"]` for German above indicates that when this language is used
-as the target language for text translation, the `formality`, `tag_handling` and `glossary_id` parameters are supported.
+For example, `["formality", "tag_handling", "glossary"]` for German above indicates that when this language is used
+as the target language for text translation, `formality`, `tag_handling` and `glossary` are supported.
Features must be included in *both* the source and target language's `features` array to be supported. For example, if
the source language French (`fr`) includes `"formality"` for text translation, but the target language Greek (`el`) does
@@ -202,7 +202,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
{
"lang": "ru",
"name": "Russian",
- "features": ["formality", "tag_handling", "glossary_id"]
+ "features": ["formality", "tag_handling", "glossary"]
}
]
```
@@ -220,7 +220,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
{
"lang": "uk",
"name": "Ukrainian",
- "features": ["formality", "tag_handling", "glossary_id"]
+ "features": ["formality", "tag_handling", "glossary"]
}
]
```
@@ -238,7 +238,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&so
{
"lang": "ru",
"name": "Russian",
- "features": ["tag_handling", "glossary_id"]
+ "features": ["tag_handling", "glossary"]
}
]
```
@@ -256,7 +256,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text&ta
{
"lang": "uk",
"name": "Ukrainian",
- "features": ["tag_handling", "glossary_id"]
+ "features": ["tag_handling", "glossary"]
}
]
```
@@ -281,7 +281,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/exceptions?product=translate_tex
{
"source_lang": "uk",
"target_lang": "ru",
- "features": ["tag_handling", "glossary_id"]
+ "features": ["tag_handling", "glossary"]
}
]
```
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index 78a8ab1..ae82007 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -2032,10 +2032,10 @@ paths:
type: string
enum:
- tag_handling
- - glossary_id
+ - glossary
example:
- tag_handling
- - glossary_id
+ - glossary
examples:
allSourceLanguages:
summary: All source languages (no product filter)
@@ -2063,12 +2063,12 @@ paths:
name: German
features:
- tag_handling
- - glossary_id
+ - glossary
- lang: en
name: English
features:
- tag_handling
- - glossary_id
+ - glossary
400:
$ref: '#/components/responses/BadRequest'
401:
@@ -2174,14 +2174,14 @@ paths:
enum:
- formality
- tag_handling
- - glossary_id
+ - glossary
- custom_instructions
- writing_style
- tone
example:
- formality
- tag_handling
- - glossary_id
+ - glossary
examples:
allTargetLanguages:
summary: All target languages (no product filter)
@@ -2210,18 +2210,18 @@ paths:
features:
- formality
- tag_handling
- - glossary_id
+ - glossary
- lang: en-US
name: English (American)
features:
- tag_handling
- - glossary_id
+ - glossary
- lang: fr
name: French
features:
- formality
- tag_handling
- - glossary_id
+ - glossary
400:
$ref: '#/components/responses/BadRequest'
401:
@@ -2295,13 +2295,13 @@ paths:
type: string
example:
- tag_handling
- - glossary_id
+ - glossary
example:
- source_lang: uk
target_lang: ru
features:
- tag_handling
- - glossary_id
+ - glossary
400:
$ref: '#/components/responses/BadRequest'
401:
From 932342a1cf5e813e1dec4f4dfc07142d4cfbb73b Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 10 Mar 2026 13:03:02 +0100
Subject: [PATCH 21/32] clarify language code casing
---
.../retrieve-languages/migrate-from-v2-languages.mdx | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index 6989ad8..1a86769 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -87,6 +87,12 @@ v2 returns a flat JSON array. v3 also returns a flat array — but each endpoint
| `name` | `name` *(unchanged)* |
| `supports_formality` | `features` *(array, product-specific)* |
+### Language code casing
+
+v2 returned language codes in non-standard casing (e.g. `EN-US`, `ZH-HANT`). v3 returns codes compliant with BCP 47: lowercase base language (`en`, `de`), uppercase region subtag (`en-US`, `pt-BR`), and title-case script subtag (`zh-Hant`).
+
+DeepL accepts language codes case-insensitively as input across all endpoints. However, if your integration stores or compares codes returned by `/v2/languages`, update those comparisons to be case-insensitive or to expect the new casing.
+
## Migrating glossary language pair queries
If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use `/v3/languages/source` and `/v3/languages/target` with `product=glossary` instead.
From 250b870e5979d7e1c682a8fa7766ea1df203f958 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 10 Mar 2026 13:04:40 +0100
Subject: [PATCH 22/32] add products endpoint
---
.../retrieve-products-beta.mdx | 4 +
...ve-supported-languages-by-product-beta.mdx | 1 +
api-reference/openapi.yaml | 107 ++++++++++++++++++
docs.json | 1 +
4 files changed, 113 insertions(+)
create mode 100644 api-reference/api-reference/retrieve-languages/retrieve-products-beta.mdx
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-products-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-products-beta.mdx
new file mode 100644
index 0000000..8dcabb4
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/retrieve-products-beta.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages/products
+title: "Retrieve language products [BETA]"
+---
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index e63f591..c163fee 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -18,6 +18,7 @@ Get information about all currently supported source and target languages across
We also provide specs that are auto-generated from DeepL's OpenAPI file. You can find them here:
- [Retrieve source languages](/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta)
- [Retrieve target languages](/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta)
+- [Retrieve products](/api-reference/api-reference/retrieve-languages/retrieve-products-beta)
- [Retrieve language pair exceptions](/api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta)
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/openapi.yaml b/api-reference/openapi.yaml
index ae82007..1c4d2a5 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -1942,6 +1942,113 @@ paths:
$ref: '#/components/responses/TooManyRequests'
security:
- auth_header: [ ]
+ /v3/languages/products:
+ get:
+ tags:
+ - MetaInformation
+ summary: Retrieve Language Products
+ operationId: getLanguageProducts
+ description: |-
+ Returns all DeepL API products, including the API endpoints they expose, and the features they support.
+
+ For each feature, the response indicates whether support depends on the source language
+ (`depends_on_source_lang`), the target language (`depends_on_target_lang`), or both. This allows
+ clients to determine feature availability for a language pair by checking the appropriate language's
+ `features` array returned by `/v3/languages/source` or `/v3/languages/target`.
+ responses:
+ 200:
+ description: JSON array where each item represents a DeepL API product.
+ headers:
+ X-Trace-ID:
+ $ref: '#/components/headers/X-Trace-ID'
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: object
+ required:
+ - name
+ - endpoints
+ - features
+ properties:
+ name:
+ description: The product identifier.
+ type: string
+ enum:
+ - translate_text
+ - translate_document
+ - glossary
+ - voice
+ - write
+ example: translate_text
+ endpoints:
+ description: API endpoints associated with this product.
+ type: array
+ items:
+ type: string
+ example:
+ - v2/translate
+ features:
+ description: |-
+ Features supported by this product. Each feature indicates whether availability
+ depends on the source language, the target language, or both.
+ type: array
+ items:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ description: The feature identifier, corresponding to values in the `features` array returned by `/v3/languages/source` and `/v3/languages/target`.
+ type: string
+ enum:
+ - formality
+ - tag_handling
+ - glossary
+ - writing_style
+ - tone
+ - custom_instructions
+ depends_on_source_lang:
+ description: Whether availability of this feature depends on the source language. Defaults to `false` if absent.
+ type: boolean
+ depends_on_target_lang:
+ description: Whether availability of this feature depends on the target language. Defaults to `false` if absent.
+ type: boolean
+ example:
+ - name: translate_text
+ endpoints:
+ - v2/translate
+ features:
+ - name: formality
+ depends_on_target_lang: true
+ - name: tag_handling
+ depends_on_source_lang: true
+ depends_on_target_lang: true
+ - name: glossary
+ depends_on_source_lang: true
+ depends_on_target_lang: true
+ - name: voice
+ endpoints:
+ - v3/voice/realtime
+ features:
+ - name: glossary
+ depends_on_source_lang: true
+ depends_on_target_lang: true
+ 400:
+ $ref: '#/components/responses/BadRequest'
+ 401:
+ $ref: '#/components/responses/Unauthorized'
+ 403:
+ $ref: '#/components/responses/Forbidden'
+ 429:
+ $ref: '#/components/responses/TooManyRequests'
+ 500:
+ $ref: '#/components/responses/InternalServerError'
+ 503:
+ $ref: '#/components/responses/ServiceUnavailable'
+ security:
+ - auth_header: []
/v3/languages/source:
get:
tags:
diff --git a/docs.json b/docs.json
index ea84e60..70e4ad9 100644
--- a/docs.json
+++ b/docs.json
@@ -202,6 +202,7 @@
"api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
"api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta",
"api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta",
+ "api-reference/api-reference/retrieve-languages/retrieve-products-beta",
"api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta",
"api-reference/api-reference/retrieve-languages/migrate-from-v2-languages"
]
From 5cba33f51a5d5a960ccf0b68c18772e2f13ac5fc Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 10 Mar 2026 16:08:52 +0100
Subject: [PATCH 23/32] make product query parameter required
---
...ve-supported-languages-by-product-beta.mdx | 41 +++----
api-reference/openapi.yaml | 110 ++----------------
2 files changed, 26 insertions(+), 125 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index c163fee..bb4673e 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -25,24 +25,26 @@ To understand how we'll update these endpoints when we add translation support f
## Basic example
-You can call the `/v3/languages/source` endpoint to retrieve a list of all supported source languages,
-and call the `/v3/languages/target` endpoint to retrieve a list of all supported target languages.
+The `product` parameter is required. Call `/v3/languages/source` and `/v3/languages/target` with the product you want
+to retrieve languages for.
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.
+The following example responses are truncated; the full API responses can include over 100 languages.
+
-```sh Example request: supported source languages
-curl -X GET 'https://api.deepl.com/v3/languages/source' \
+```sh Example request: supported source languages for text translation
+curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
-```http Example request: supported source languages
-GET /v3/languages/source HTTP/2
+```http Example request: supported source languages for text translation
+GET /v3/languages/source?product=translate_text HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
@@ -50,7 +52,6 @@ User-Agent: YourApp/1.2.3
-The following example response is truncated; the full API response includes over 100 languages.
```json Example response
[
@@ -79,15 +80,6 @@ The following example response is truncated; the full API response includes over
]
```
-## Filtering by product
-
-For the `/v3/languages/source` and `/v3/languages/target` endpoints you may also specify the `product` query parameter
-as a filter, to return only source or target languages supporting that product.
-In this case the `products` array is no longer included in the response.
-
-Instead, each source or target language includes a `features` array indicating which product-specific capabilities are
-supported for the language:
-
@@ -151,12 +143,10 @@ The `product` query parameter identifies which DeepL API product you are queryin
feature value, explained in the following section.
-As we add new products to the DeepL API, the `products` list for each supported language will be extended.
-
## Product features
-As described earlier, when the `product` query parameter is specified, language objects may include a `features` array.
-The included features indicate which optional parameters are supported for that language.
+Each language object includes a `features` array indicating which optional capabilities are supported for that language
+with the requested product.
For example, `["formality", "tag_handling", "glossary"]` for German above indicates that when this language is used
as the target language for text translation, `formality`, `tag_handling` and `glossary` are supported.
@@ -294,23 +284,20 @@ You can apply these exceptions in client logic, overriding the responses from th
The v3 language endpoints are designed to be forward-compatible:
-- New products may be added to the `products` array
- New features may be added to the `features` array
- New languages will be added as DeepL support expands
- Existing fields will not be removed or changed in backwards-incompatible ways
- Build your integration to gracefully handle new values in the `products` and `features` arrays.
+ Build your integration to gracefully handle new values in the `features` array.
## Best practices
1. **Cache responses**: Language support changes infrequently. Consider caching responses for up to 1 hour.
-2. **Filter by product**: Use the `product` parameter when you only need languages for a specific product — this reduces response size and includes feature information.
-
-3. **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` array on language objects rather than assuming support (e.g. for formality, glossary use, or writing style).
-4. **Handle forward compatibility**: Ignore unknown values in `products` and `features` arrays to remain compatible as new products and capabilities are added.
+3. **Handle forward compatibility**: Ignore unknown values in the `features` array to remain compatible as new capabilities are added.
-5. **Use specific variants**: For target languages, prefer specific regional variants (e.g., `"en-US"`, `"en-GB"`) when the distinction matters to your users.
+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/openapi.yaml b/api-reference/openapi.yaml
index 1c4d2a5..ffec5ec 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -2056,16 +2056,11 @@ paths:
summary: Retrieve Source Languages
operationId: getSourceLanguages
description: |-
- Returns source languages supported by one or more DeepL API products.
-
- When no `product` parameter is specified, each language includes a `products` array
- indicating which products support it. When `product` is specified, only languages
- for that product are returned, the `products` field is omitted, and source languages
- may include a `features` array listing product-specific capabilities.
+ Returns source languages supported by the specified DeepL API product.
parameters:
- name: product
in: query
- required: false
+ required: true
schema:
type: string
enum:
@@ -2075,7 +2070,7 @@ paths:
- voice
- write
description: |-
- Filter languages by product. Supported values: `translate_text`, `translate_document`,
+ The product to retrieve source languages for. Supported values: `translate_text`, `translate_document`,
`glossary`, `voice`, `write`.
- name: target_lang
in: query
@@ -2101,6 +2096,7 @@ paths:
required:
- lang
- name
+ - features
properties:
lang:
description: The language code of the given language.
@@ -2110,30 +2106,10 @@ paths:
description: Name of the language in English.
type: string
example: German
- products:
- description: |-
- Array of product identifiers indicating which products support this language.
- Only present when no `product` query parameter is specified.
- type: array
- items:
- type: string
- enum:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
- example:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
features:
description: |-
- Array of feature strings indicating capabilities for this language with the
- specified product. Only present when a `product` query parameter is specified
- and the language supports one or more features for that product.
+ Array of feature strings indicating capabilities supported for this language
+ with the specified product.
type: array
items:
type: string
@@ -2144,25 +2120,6 @@ paths:
- tag_handling
- glossary
examples:
- allSourceLanguages:
- summary: All source languages (no product filter)
- value:
- - lang: de
- name: German
- products:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
- - lang: en
- name: English
- products:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
translateTextSources:
summary: Source languages for text translation
value:
@@ -2197,16 +2154,11 @@ paths:
summary: Retrieve Target Languages
operationId: getTargetLanguages
description: |-
- Returns target languages supported by one or more DeepL API products.
-
- When no `product` parameter is specified, each language includes a `products` array
- indicating which products support it. When `product` is specified, only languages
- for that product are returned, the `products` field is omitted, and target languages
- may include a `features` array listing product-specific capabilities.
+ Returns target languages supported by the specified DeepL API product.
parameters:
- name: product
in: query
- required: false
+ required: true
schema:
type: string
enum:
@@ -2216,7 +2168,7 @@ paths:
- voice
- write
description: |-
- Filter languages by product. Supported values: `translate_text`, `translate_document`,
+ The product to retrieve target languages for. Supported values: `translate_text`, `translate_document`,
`glossary`, `voice`, `write`.
- name: source_lang
in: query
@@ -2242,6 +2194,7 @@ paths:
required:
- lang
- name
+ - features
properties:
lang:
description: The language code of the given language.
@@ -2251,30 +2204,10 @@ paths:
description: Name of the language in English.
type: string
example: English (American)
- products:
- description: |-
- Array of product identifiers indicating which products support this language.
- Only present when no `product` query parameter is specified.
- type: array
- items:
- type: string
- enum:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
- example:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
features:
description: |-
- Array of feature strings indicating capabilities for this language with the
- specified product. Only present when a `product` query parameter is specified
- and the language supports one or more features for that product.
+ Array of feature strings indicating capabilities supported for this language
+ with the specified product.
type: array
items:
type: string
@@ -2290,25 +2223,6 @@ paths:
- tag_handling
- glossary
examples:
- allTargetLanguages:
- summary: All target languages (no product filter)
- value:
- - lang: en-US
- name: English (American)
- products:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
- - lang: fr
- name: French
- products:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
translateTextTargets:
summary: Target languages for text translation
value:
From f7e34bce457403277c4d4266f3dba8304897a312 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Tue, 10 Mar 2026 16:10:39 +0100
Subject: [PATCH 24/32] add docs about products endpoint
---
...ve-supported-languages-by-product-beta.mdx | 59 ++++++++++++++-----
1 file changed, 45 insertions(+), 14 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index bb4673e..cb88710 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -53,28 +53,22 @@ User-Agent: YourApp/1.2.3
-```json Example response
+```json Example source languages response
[
{
"lang": "de",
"name": "German",
- "products": [
- "translate_text",
- "translate_document",
- "glossary",
- "voice",
- "write"
+ "features": [
+ "tag_handling",
+ "glossary"
]
},
{
"lang": "en",
"name": "English",
- "products": [
- "translate_text",
- "translate_document",
- "glossary",
- "voice",
- "write"
+ "features": [
+ "tag_handling",
+ "glossary"
]
}
]
@@ -101,7 +95,7 @@ User-Agent: YourApp/1.2.3
-```json Example response
+```json Example target languages response
[
{
"lang": "de",
@@ -143,6 +137,43 @@ The `product` query parameter identifies which DeepL API product you are queryin
feature value, explained in the following section.
+### Retrieving products programmatically
+
+Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically,
+without relying on documentation. For each feature, the response indicates whether support depends on the source
+language, the target language, or both — allowing clients to determine feature availability for a language pair
+by intersecting the appropriate `features` arrays.
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/products' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (truncated)
+[
+ {
+ "name": "translate_text",
+ "endpoints": ["v2/translate"],
+ "features": [
+ {
+ "name": "formality",
+ "depends_on_target_lang": true
+ },
+ {
+ "name": "tag_handling",
+ "depends_on_source_lang": true,
+ "depends_on_target_lang": true
+ },
+ {
+ "name": "glossary",
+ "depends_on_source_lang": true,
+ "depends_on_target_lang": true
+ }
+ ]
+ }
+]
+```
+
## Product features
Each language object includes a `features` array indicating which optional capabilities are supported for that language
From cf656b0df9aac29224fc4442ce92ac87db5f92e5 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 11:43:19 +0100
Subject: [PATCH 25/32] removing source_lang and target_lang filters from
source and target endpoints
---
...ve-supported-languages-by-product-beta.mdx | 84 +------------------
api-reference/openapi.yaml | 18 ----
2 files changed, 1 insertion(+), 101 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index cb88710..e7a9c16 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -201,91 +201,9 @@ It is complex to handle these cases, so we design our API endpoints to perform t
example, by ignoring formality support and continuing with the translation rather than failing the request.
However, in some cases information about these exceptions may be useful, so this section explains how to retrieve it.
-### `source_lang` and `target_lang` query parameters
-
-You may also specify a `source_lang` or `target_lang` query parameter in addition to the `product` query parameter:
-- for `/v3/languages/source`, the `target_lang` parameter indicates the target language for which you want to retrieve
-language support
-- for `/v3/languages/target`, the `source_lang` parameter indicates the source language for which you want to retrieve
-language support
-These parameters will modify the feature support information returned for each language, applying any of these
-exceptional cases as described above.
-
-Continuing the hypothetical Ukrainian to Russian example: querying target languages for text translation without a
-source filter shows Russian with `formality` support, since Russian generally supports formality as a target language:
-
-```sh
-curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example target languages response (truncated)
-[
- {
- "lang": "ru",
- "name": "Russian",
- "features": ["formality", "tag_handling", "glossary"]
- }
-]
-```
-
-Similarly, querying source languages for text translation without a target filter shows Ukrainian with `formality`
-support, since Ukrainian generally supports formality as a source language:
-
-```sh
-curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example source languages response (truncated)
-[
- {
- "lang": "uk",
- "name": "Ukrainian",
- "features": ["formality", "tag_handling", "glossary"]
- }
-]
-```
-
-However, specifying `source_lang=uk` applies the language-pair exception, and Russian is returned without `formality` indicating
-the exception:
-
-```sh
-curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text&source_lang=uk' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example target languages response, filtering for source_lang=uk (truncated)
-[
- {
- "lang": "ru",
- "name": "Russian",
- "features": ["tag_handling", "glossary"]
- }
-]
-```
-
-Similarly, querying source languages while specifying `target_lang=ru` applies the language-pair exception, and
-Ukrainian is returned without `formality` indicating the exception:
-
-```sh
-curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text&target_lang=ru' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example source languages response, filtering for target_lang=ru (truncated)
-[
- {
- "lang": "uk",
- "name": "Ukrainian",
- "features": ["tag_handling", "glossary"]
- }
-]
-```
-
### Retrieving language pair exceptions directly
-Language pair exceptions are also available directly via the `/v3/languages/exceptions` endpoint. The `product` query
+Language pair exceptions are available directly via the `/v3/languages/exceptions` endpoint. The `product` query
parameter is required to specify the product for which you want to retrieve exceptions.
The response includes a list of language pairs for which exceptions exist, with their actual feature support.
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index ffec5ec..f8673c0 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -2072,15 +2072,6 @@ paths:
description: |-
The product to retrieve source languages for. Supported values: `translate_text`, `translate_document`,
`glossary`, `voice`, `write`.
- - name: target_lang
- in: query
- required: false
- schema:
- type: string
- example: en-US
- description: |-
- Filter source languages to those compatible with a specific target language.
- Must be used together with `product`. Language code must be valid (e.g. `en`, `en-US`, `fr`).
responses:
200:
description: JSON array where each item represents a supported source language.
@@ -2170,15 +2161,6 @@ paths:
description: |-
The product to retrieve target languages for. Supported values: `translate_text`, `translate_document`,
`glossary`, `voice`, `write`.
- - name: source_lang
- in: query
- required: false
- schema:
- type: string
- example: de
- description: |-
- Filter target languages to those compatible with a specific source language.
- Must be used together with `product`. Language code must be valid (e.g. `de`, `en`, `fr`).
responses:
200:
description: JSON array where each item represents a supported target language.
From ad63ca0fd6ff0fe21f602ce86d60ae6597642e97 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 12:08:48 +0100
Subject: [PATCH 26/32] reflow text in overview for clarity
---
.../migrate-from-v2-languages.mdx | 20 +++---
...ve-supported-languages-by-product-beta.mdx | 67 +++++++++----------
2 files changed, 42 insertions(+), 45 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index 1a86769..c04a867 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -33,9 +33,9 @@ v2 languages are implicitly tied to text and document translation. v3 introduces
| v2 | v3 `product` value |
|---|---|
-| *(implicit — text/document translation only)* | `translate_text` |
-| *(implicit — text/document translation only)* | `translate_document` |
-| *(not supported — separate `/v2/glossary-language-pairs` endpoint)* | `glossary` |
+| *(implicit, text/document translation only)* | `translate_text` |
+| *(implicit, text/document translation only)* | `translate_document` |
+| *(separate `/v2/glossary-language-pairs` endpoint)* | `glossary` |
| *(not supported)* | `voice` |
| *(not supported)* | `write` |
@@ -47,7 +47,7 @@ v2 target languages include a boolean `supports_formality` field. v3 replaces th
| v2 field | v3 equivalent |
|---|---|
-| `"supports_formality": true` | `"features": ["formality"]` on both source and target language (when `product` is specified) |
+| `"supports_formality": true` | `"features": ["formality"]` on the target language |
For example, querying target languages for text translation:
@@ -73,11 +73,7 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
The response indicates German supports `formality`, but English (American) does not.
-The `features` array only appears on a language object when a `product` parameter is specified. See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta) for the full list of features per product.
-
-### Flat array response
-
-v2 returns a flat JSON array. v3 also returns a flat array — but each endpoint returns only its own list (sources or targets), so there is no wrapper object.
+See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta) for the full list of features per product.
### Response field names
@@ -95,4 +91,8 @@ DeepL accepts language codes case-insensitively as input across all endpoints. H
## Migrating glossary language pair queries
-If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use `/v3/languages/source` and `/v3/languages/target` with `product=glossary` instead.
+If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use one of the following:
+- `/v3/languages/source?product=glossary` and `/v3/languages/target?product=glossary` to check glossary management support.
+
+
+These endpoints list the source and target languages that are supported for glossaries, any combination of which can be used.
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index e7a9c16..75dedae 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -23,10 +23,28 @@ We also provide specs that are auto-generated from DeepL's OpenAPI file. You can
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).
-## Basic example
+## Products list
-The `product` parameter is required. Call `/v3/languages/source` and `/v3/languages/target` with the product you want
-to retrieve languages for.
+The `product` parameter is required on `/v3/languages/source` and `/v3/languages/target`. It identifies which
+DeepL API product you are querying language support for:
+
+| Value | Description |
+|---|---|
+| `translate_text` | Text translation via the `/v2/translate` endpoint |
+| `translate_document` | Document translation via the `/v2/document` endpoint |
+| `voice` | Speech-to-text and speech-to-speech via the `/v3/voice` endpoints |
+| `write` | Text improvement via the `/v2/write` endpoints |
+| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
+
+
+ `glossary` is a product 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`
+ feature value, explained in a later section.
+
+
+## Basic example
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.
@@ -52,7 +70,6 @@ User-Agent: YourApp/1.2.3
-
```json Example source languages response
[
{
@@ -117,27 +134,22 @@ User-Agent: YourApp/1.2.3
]
```
-## Products list
+## Product features
-The `product` query parameter identifies which DeepL API product you are querying language support for:
+Each language object includes a `features` array indicating which optional capabilities are supported for that language
+with the requested product.
-| Value | Description |
-|---|---|
-| `translate_text` | Text translation via the `/v2/translate` endpoint |
-| `translate_document` | Document translation via the `/v2/document` endpoint |
-| `voice` | Speech-to-text and speech-to-speech via the `/v3/voice` endpoints |
-| `write` | Text improvement via the `/v2/write` endpoints |
-| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
+For example, `["formality", "tag_handling", "glossary"]` for German above indicates that when this language is used
+as the target language for text translation, `formality`, `tag_handling` and `glossary` are supported.
-
- `glossary` is a product value indicating glossaries can be created for that language, and managed via the glossary
- management endpoints.
+Features must be included in *both* the source and target language's `features` array to be supported. For example, if
+the source language French (`fr`) includes `"formality"` for text translation, but the target language Greek (`el`) does
+not, then text translations from French to Greek are possible but will not support formality.
- Support for glossaries within specific products (for example text translation) is indicated by the `glossary`
- feature value, explained in the following section.
-
+API endpoints describe in their documentation which request parameters are language-dependent, and indicate the
+feature values to check for in the `features` array.
-### Retrieving products programmatically
+## Retrieving products programmatically
Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically,
without relying on documentation. For each feature, the response indicates whether support depends on the source
@@ -174,21 +186,6 @@ curl -X GET 'https://api.deepl.com/v3/languages/products' \
]
```
-## Product features
-
-Each language object includes a `features` array indicating which optional capabilities are supported for that language
-with the requested product.
-
-For example, `["formality", "tag_handling", "glossary"]` for German above indicates that when this language is used
-as the target language for text translation, `formality`, `tag_handling` and `glossary` are supported.
-
-Features must be included in *both* the source and target language's `features` array to be supported. For example, if
-the source language French (`fr`) includes `"formality"` for text translation, but the target language Greek (`el`) does
-not, then text translations from French to Greek are possible but will not support formality.
-
-API endpoints describe in their documentation which request parameters are language-dependent, and indicate the
-feature values to check for in the `features` array.
-
## Language pair exceptions
In rare cases, feature support for a specific language pair may differ from the feature support returned for the source
From 23b93ff06a9999ae842ce3bfb04d4f5fc8025e97 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 12:28:32 +0100
Subject: [PATCH 27/32] better migration explanation for glossaries
---
.../retrieve-languages/migrate-from-v2-languages.mdx | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index c04a867..a5406c4 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -92,7 +92,7 @@ DeepL accepts language codes case-insensitively as input across all endpoints. H
## Migrating glossary language pair queries
If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use one of the following:
-- `/v3/languages/source?product=glossary` and `/v3/languages/target?product=glossary` to check glossary management support.
-
-These endpoints list the source and target languages that are supported for glossaries, any combination of which can be used.
+- `/v3/languages/source?product=glossary` and `/v3/languages/target?product=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Any combination of the returned source and target languages is a valid glossary language pair.
+- `/v3/languages/source?product=translate_text` and `/v3/languages/target?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.
From ea453c8772e8782abb8826efa07f03d1ae9ec064 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 12:42:44 +0100
Subject: [PATCH 28/32] rewording Product features section
---
...ve-supported-languages-by-product-beta.mdx | 21 ++++++++++---------
1 file changed, 11 insertions(+), 10 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 75dedae..bc38e86 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -32,7 +32,7 @@ DeepL API product you are querying language support for:
|---|---|
| `translate_text` | Text translation via the `/v2/translate` endpoint |
| `translate_document` | Document translation via the `/v2/document` endpoint |
-| `voice` | Speech-to-text and speech-to-speech via the `/v3/voice` endpoints |
+| `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 |
@@ -139,20 +139,21 @@ User-Agent: YourApp/1.2.3
Each language object includes a `features` array indicating which optional capabilities are supported for that language
with the requested product.
-For example, `["formality", "tag_handling", "glossary"]` for German above indicates that when this language is used
-as the target language for text translation, `formality`, `tag_handling` and `glossary` are supported.
+A feature may depend on the source language, the target language, or both. For example, for text-translation:
-Features must be included in *both* the source and target language's `features` array to be supported. For example, if
-the source language French (`fr`) includes `"formality"` for text translation, but the target language Greek (`el`) does
-not, then text translations from French to Greek are possible but will not support formality.
+- **Target-only**: `formality` depends only on the target language used for translation. Check that `"formality"` is
+ present in the target language's `features` array.
+- **Source-and-target** `tag_handling` and `glossary` depend on both the source and target languages used in
+ translation. Check that `"tag_handling"` or `"glossary"` is present in *both* the source and target language's
+ `features` arrays to be supported for that pair.
-API endpoints describe in their documentation which request parameters are language-dependent, and indicate the
-feature values to check for in the `features` array.
+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.
## Retrieving products programmatically
-Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically,
-without relying on documentation. For each feature, the response indicates whether support depends on the source
+Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically.
+For each feature, the response indicates whether support depends on the source
language, the target language, or both — allowing clients to determine feature availability for a language pair
by intersecting the appropriate `features` arrays.
From 7c695b2ad927efc285d76a01bc0a75ed9d5d6ba6 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 13:02:22 +0100
Subject: [PATCH 29/32] rewording
---
...ieve-supported-languages-by-product-beta.mdx | 17 +++++++++++------
api-reference/openapi.yaml | 6 ++++--
2 files changed, 15 insertions(+), 8 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index bc38e86..941c4a0 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -139,13 +139,14 @@ User-Agent: YourApp/1.2.3
Each language object includes a `features` array indicating which optional capabilities are supported for that language
with the requested product.
-A feature may depend on the source language, the target language, or both. For example, for text-translation:
+A feature may depend on the source language, the target language, or both. For example, for text translation:
-- **Target-only**: `formality` depends only on the target language used for translation. Check that `"formality"` is
- present in the target language's `features` array.
-- **Source-and-target** `tag_handling` and `glossary` depend on both the source and target languages used in
- translation. Check that `"tag_handling"` or `"glossary"` is present in *both* the source and target language's
- `features` arrays to be supported for that pair.
+- **Target-only**: `formality` depends only on the target language. Check that `"formality"` is present in the target
+ language's `features` array.
+- **Source-and-target**: `tag_handling` and `glossary` depend on both the source and target languages. Check that the
+ feature is present in *both* the source and target language's `features` arrays.
+
+Source-only features are also supported by the schema, though none exist currently.
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.
@@ -172,6 +173,10 @@ curl -X GET 'https://api.deepl.com/v3/languages/products' \
"name": "formality",
"depends_on_target_lang": true
},
+ {
+ "name": "custom_instructions",
+ "depends_on_target_lang": true
+ },
{
"name": "tag_handling",
"depends_on_source_lang": true,
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index f8673c0..835f072 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -2004,11 +2004,11 @@ paths:
type: string
enum:
- formality
+ - custom_instructions
- tag_handling
- glossary
- writing_style
- tone
- - custom_instructions
depends_on_source_lang:
description: Whether availability of this feature depends on the source language. Defaults to `false` if absent.
type: boolean
@@ -2022,6 +2022,8 @@ paths:
features:
- name: formality
depends_on_target_lang: true
+ - name: custom_instructions
+ depends_on_target_lang: true
- name: tag_handling
depends_on_source_lang: true
depends_on_target_lang: true
@@ -2195,9 +2197,9 @@ paths:
type: string
enum:
- formality
+ - custom_instructions
- tag_handling
- glossary
- - custom_instructions
- writing_style
- tone
example:
From 7e5ac35f4a1b449d30c130f361dedfdc6aa2b819 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 13:58:56 +0100
Subject: [PATCH 30/32] rewording
---
...ve-supported-languages-by-product-beta.mdx | 19 +++++++++++++------
1 file changed, 13 insertions(+), 6 deletions(-)
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 941c4a0..822dd44 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -15,7 +15,7 @@ Get information about all currently supported source and target languages across
for a full list of differences and code examples.
-We also provide specs that are auto-generated from DeepL's OpenAPI file. You can find them here:
+We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:
- [Retrieve source languages](/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta)
- [Retrieve target languages](/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta)
- [Retrieve products](/api-reference/api-reference/retrieve-languages/retrieve-products-beta)
@@ -25,7 +25,8 @@ To understand how we'll update these endpoints when we add translation support f
## Products list
-The `product` parameter is required on `/v3/languages/source` and `/v3/languages/target`. It identifies which
+To retrieve language support, decide which DeepL product you're building for, then call `/v3/languages/source` and
+`/v3/languages/target` with the appropriate `product` value. The `product` parameter is required and identifies which
DeepL API product you are querying language support for:
| Value | Description |
@@ -46,6 +47,9 @@ DeepL API product you are querying language support for:
## 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.
+
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.
@@ -200,9 +204,10 @@ and target languages individually. This occurs due to intricacies and language-s
A hypothetical example: text translation formality is supported for source language Ukrainian, and it is also supported
for target language Russian. However, translating specifically from Ukrainian to Russian does *not* support formality.
-It is complex to handle these cases, so we design our API endpoints to perform the "best effort" in such cases. For
-example, by ignoring formality support and continuing with the translation rather than failing the request.
-However, in some cases information about these exceptions may be useful, so this section explains how to retrieve it.
+It is complex to handle these cases, so we design our API endpoints to perform the "best effort" in such cases.
+When a request uses a feature that is unsupported for the specific language pair, the API attempts to complete the
+request by disabling the unsupported feature rather than failing. However, in some cases information about these
+exceptions may be useful, so this section explains how to retrieve it.
### Retrieving language pair exceptions directly
@@ -230,7 +235,9 @@ curl -X GET 'https://api.deepl.com/v3/languages/exceptions?product=translate_tex
```
You can apply these exceptions in client logic, overriding the responses from the `/v3/languages/source` and
-`/v3/languages/target` endpoints for those specific language pairs.
+`/v3/languages/target` endpoints for those specific language pairs. The exception's `features` array is the complete
+and authoritative feature list for that pair — it replaces the individual source and target language `features` arrays
+entirely, regardless of whether a feature is target-only or source-and-target.
## API stability
From 5281a163b4ee437147bf3c9221ae3cc7403f1a77 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 21:56:25 +0100
Subject: [PATCH 31/32] combine /source and /target endpoints
---
.../migrate-from-v2-languages.mdx | 34 ++--
.../retrieve-languages-beta.mdx | 4 +
.../retrieve-source-languages-beta.mdx | 4 -
...ve-supported-languages-by-product-beta.mdx | 100 ++++------
.../retrieve-target-languages-beta.mdx | 4 -
api-reference/openapi.yaml | 174 +++++-------------
docs.json | 3 +-
7 files changed, 110 insertions(+), 213 deletions(-)
create mode 100644 api-reference/api-reference/retrieve-languages/retrieve-languages-beta.mdx
delete mode 100644 api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx
delete mode 100644 api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx
diff --git a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
index a5406c4..dad9567 100644
--- a/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
+++ b/api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx
@@ -11,20 +11,20 @@ This page covers the differences between the `/v2/languages` endpoint and the v3
## What changed
-### Separate endpoints for source and target
+### Single endpoint for source and target
-v2 uses a single endpoint with a `type` query parameter:
+v2 uses a single endpoint with a `type` query parameter to distinguish source from target:
```
GET /v2/languages?type=source
GET /v2/languages?type=target
```
-v3 uses two dedicated endpoints:
+v3 uses a single endpoint that returns all languages for a product, with each language indicating whether it is
+usable as a source, a target, or both:
```
-GET /v3/languages/source
-GET /v3/languages/target
+GET /v3/languages?product=translate_text
```
### New product identifiers
@@ -47,12 +47,12 @@ v2 target languages include a boolean `supports_formality` field. v3 replaces th
| v2 field | v3 equivalent |
|---|---|
-| `"supports_formality": true` | `"features": ["formality"]` on the target language |
+| `"supports_formality": true` | `"features": ["formality"]` on the language object |
-For example, querying target languages for text translation:
+For example, querying languages for text translation:
```sh
-curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
+curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
@@ -61,11 +61,15 @@ curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
{
"lang": "de",
"name": "German",
+ "usable_as_source": true,
+ "usable_as_target": true,
"features": ["formality", "tag_handling", "glossary"]
},
{
"lang": "en-US",
"name": "English (American)",
+ "usable_as_source": false,
+ "usable_as_target": true,
"features": ["tag_handling", "glossary"]
}
]
@@ -77,11 +81,11 @@ See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supp
### Response field names
-| v2 field | v3 field |
-|---|---|
-| `language` | `lang` |
-| `name` | `name` *(unchanged)* |
-| `supports_formality` | `features` *(array, product-specific)* |
+| v2 field | v3 field |
+|----------------------|------------------------|
+| `language` | `lang` |
+| `name` | `name` *(unchanged)* |
+| `supports_formality` | `features["formality]` |
### Language code casing
@@ -93,6 +97,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:
-- `/v3/languages/source?product=glossary` and `/v3/languages/target?product=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Any combination of the returned source and target languages is a valid glossary language pair.
-- `/v3/languages/source?product=translate_text` and `/v3/languages/target?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.
+- `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.
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-languages-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-languages-beta.mdx
new file mode 100644
index 0000000..8c4ae59
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/retrieve-languages-beta.mdx
@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages
+title: "Retrieve languages [BETA]"
+---
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx
deleted file mode 100644
index 7a231ba..0000000
--- a/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: get /v3/languages/source
-title: "Retrieve source languages [BETA]"
----
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
index 822dd44..0552624 100644
--- a/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
+++ b/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta.mdx
@@ -4,7 +4,7 @@ sidebarTitle: 'Overview'
description: "API reference for retrieving supported languages with the DeepL API across all products."
---
-Get information about all currently supported source and target languages across all DeepL API products.
+Get information about all currently supported languages across all DeepL API products.
The `/v3/languages` endpoints provide a single source of truth for language and feature support across all DeepL
@@ -16,8 +16,7 @@ Get information about all currently supported source and target languages across
We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:
-- [Retrieve source languages](/api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta)
-- [Retrieve target languages](/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta)
+- [Retrieve languages](/api-reference/api-reference/retrieve-languages/retrieve-languages-beta)
- [Retrieve products](/api-reference/api-reference/retrieve-languages/retrieve-products-beta)
- [Retrieve language pair exceptions](/api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta)
@@ -25,9 +24,9 @@ To understand how we'll update these endpoints when we add translation support f
## Products list
-To retrieve language support, decide which DeepL product you're building for, then call `/v3/languages/source` and
-`/v3/languages/target` with the appropriate `product` value. The `product` parameter is required and identifies which
-DeepL API product you are querying language support for:
+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
+are querying language support for:
| Value | Description |
|---|---|
@@ -58,15 +57,15 @@ The following example responses are truncated; the full API responses can includ
-```sh Example request: supported source languages for text translation
-curl -X GET 'https://api.deepl.com/v3/languages/source?product=translate_text' \
+```sh Example request: languages for text translation
+curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
-```http Example request: supported source languages for text translation
-GET /v3/languages/source?product=translate_text HTTP/2
+```http Example request: languages for text translation
+GET /v3/languages?product=translate_text HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3
@@ -74,12 +73,15 @@ User-Agent: YourApp/1.2.3
-```json Example source languages response
+```json Example response
[
{
"lang": "de",
"name": "German",
+ "usable_as_source": true,
+ "usable_as_target": true,
"features": [
+ "formality",
"tag_handling",
"glossary"
]
@@ -87,49 +89,18 @@ User-Agent: YourApp/1.2.3
{
"lang": "en",
"name": "English",
+ "usable_as_source": true,
+ "usable_as_target": false,
"features": [
"tag_handling",
"glossary"
]
- }
-]
-```
-
-
-
-
-```sh Example request: target languages for text translation
-curl -X GET 'https://api.deepl.com/v3/languages/target?product=translate_text' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-
-
-
-```http Example request: target languages for text translation
-GET /v3/languages/target?product=translate_text HTTP/2
-Host: api.deepl.com
-Authorization: DeepL-Auth-Key [yourAuthKey]
-User-Agent: YourApp/1.2.3
-```
-
-
-
-
-```json Example target languages response
-[
- {
- "lang": "de",
- "name": "German",
- "features": [
- "formality",
- "tag_handling",
- "glossary"
- ]
},
{
"lang": "en-US",
"name": "English (American)",
+ "usable_as_source": false,
+ "usable_as_target": true,
"features": [
"tag_handling",
"glossary"
@@ -143,12 +114,12 @@ User-Agent: YourApp/1.2.3
Each language object includes a `features` array indicating which optional capabilities are supported for that language
with the requested product.
-A feature may depend on the source language, the target language, or both. For example, for text translation:
+A feature may be required on the source language, the target language, or both. For example, for text translation:
-- **Target-only**: `formality` depends only on the target language. Check that `"formality"` is present in the target
- language's `features` array.
-- **Source-and-target**: `tag_handling` and `glossary` depend on both the source and target languages. Check that the
- feature is present in *both* the source and target language's `features` arrays.
+- **Target-only**: `formality` is required only on the target language. Check that `"formality"` is present in the
+ target language's `features` array.
+- **Source-and-target**: `tag_handling` and `glossary` are required on both languages. Check that the feature is
+ present in *both* the source and target language's `features` arrays.
Source-only features are also supported by the schema, though none exist currently.
@@ -158,9 +129,9 @@ which language feature value to check, and whether to check the source language,
## Retrieving products programmatically
Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically.
-For each feature, the response indicates whether support depends on the source
-language, the target language, or both — allowing clients to determine feature availability for a language pair
-by intersecting the appropriate `features` arrays.
+For each feature, the response indicates whether support is required on the source language, the target language,
+or both — allowing clients to determine feature availability for a language pair by checking the appropriate
+`features` arrays.
```sh
curl -X GET 'https://api.deepl.com/v3/languages/products' \
@@ -175,21 +146,21 @@ curl -X GET 'https://api.deepl.com/v3/languages/products' \
"features": [
{
"name": "formality",
- "depends_on_target_lang": true
+ "required_on_target": true
},
{
"name": "custom_instructions",
- "depends_on_target_lang": true
+ "required_on_target": true
},
{
"name": "tag_handling",
- "depends_on_source_lang": true,
- "depends_on_target_lang": true
+ "required_on_source": true,
+ "required_on_target": true
},
{
"name": "glossary",
- "depends_on_source_lang": true,
- "depends_on_target_lang": true
+ "required_on_source": true,
+ "required_on_target": true
}
]
}
@@ -204,7 +175,6 @@ and target languages individually. This occurs due to intricacies and language-s
A hypothetical example: text translation formality is supported for source language Ukrainian, and it is also supported
for target language Russian. However, translating specifically from Ukrainian to Russian does *not* support formality.
-It is complex to handle these cases, so we design our API endpoints to perform the "best effort" in such cases.
When a request uses a feature that is unsupported for the specific language pair, the API attempts to complete the
request by disabling the unsupported feature rather than failing. However, in some cases information about these
exceptions may be useful, so this section explains how to retrieve it.
@@ -234,10 +204,10 @@ curl -X GET 'https://api.deepl.com/v3/languages/exceptions?product=translate_tex
]
```
-You can apply these exceptions in client logic, overriding the responses from the `/v3/languages/source` and
-`/v3/languages/target` endpoints for those specific language pairs. The exception's `features` array is the complete
-and authoritative feature list for that pair — it replaces the individual source and target language `features` arrays
-entirely, regardless of whether a feature is target-only or source-and-target.
+You can apply these exceptions in client logic. The exception's `features` array is the authoritative feature list
+for that pair — it replaces the individual language `features` arrays entirely for that combination, regardless of
+whether a feature is target-only or source-and-target. Skip the normal intersection logic and use the exception
+`features` directly.
## API stability
diff --git a/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx b/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx
deleted file mode 100644
index 6dcc26a..0000000
--- a/api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta.mdx
+++ /dev/null
@@ -1,4 +0,0 @@
----
-openapi: get /v3/languages/target
-title: "Retrieve target languages [BETA]"
----
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index 835f072..d40baee 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -1951,10 +1951,10 @@ paths:
description: |-
Returns all DeepL API products, including the API endpoints they expose, and the features they support.
- For each feature, the response indicates whether support depends on the source language
- (`depends_on_source_lang`), the target language (`depends_on_target_lang`), or both. This allows
+ For each feature, the response indicates whether support is required on the source language
+ (`required_on_source`), the target language (`required_on_target`), or both. This allows
clients to determine feature availability for a language pair by checking the appropriate language's
- `features` array returned by `/v3/languages/source` or `/v3/languages/target`.
+ `features` array returned by `GET /v3/languages`.
responses:
200:
description: JSON array where each item represents a DeepL API product.
@@ -1991,8 +1991,8 @@ paths:
- v2/translate
features:
description: |-
- Features supported by this product. Each feature indicates whether availability
- depends on the source language, the target language, or both.
+ Features supported by this product. Each feature indicates whether support is
+ required on the source language, the target language, or both.
type: array
items:
type: object
@@ -2000,7 +2000,7 @@ paths:
- name
properties:
name:
- description: The feature identifier, corresponding to values in the `features` array returned by `/v3/languages/source` and `/v3/languages/target`.
+ description: The feature identifier, corresponding to values in the `features` array returned by `GET /v3/languages`.
type: string
enum:
- formality
@@ -2009,11 +2009,11 @@ paths:
- glossary
- writing_style
- tone
- depends_on_source_lang:
- description: Whether availability of this feature depends on the source language. Defaults to `false` if absent.
+ required_on_source:
+ description: Whether support for this feature is required on the source language. Defaults to `false` if absent.
type: boolean
- depends_on_target_lang:
- description: Whether availability of this feature depends on the target language. Defaults to `false` if absent.
+ required_on_target:
+ description: Whether support for this feature is required on the target language. Defaults to `false` if absent.
type: boolean
example:
- name: translate_text
@@ -2021,22 +2021,22 @@ paths:
- v2/translate
features:
- name: formality
- depends_on_target_lang: true
+ required_on_target: true
- name: custom_instructions
- depends_on_target_lang: true
+ required_on_target: true
- name: tag_handling
- depends_on_source_lang: true
- depends_on_target_lang: true
+ required_on_source: true
+ required_on_target: true
- name: glossary
- depends_on_source_lang: true
- depends_on_target_lang: true
+ required_on_source: true
+ required_on_target: true
- name: voice
endpoints:
- v3/voice/realtime
features:
- name: glossary
- depends_on_source_lang: true
- depends_on_target_lang: true
+ required_on_source: true
+ required_on_target: true
400:
$ref: '#/components/responses/BadRequest'
401:
@@ -2051,14 +2051,16 @@ paths:
$ref: '#/components/responses/ServiceUnavailable'
security:
- auth_header: []
- /v3/languages/source:
+ /v3/languages:
get:
tags:
- MetaInformation
- summary: Retrieve Source Languages
- operationId: getSourceLanguages
+ summary: Retrieve Languages
+ operationId: getLanguages
description: |-
- Returns source languages supported by the specified DeepL API product.
+ Returns languages supported by the specified DeepL API product. 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.
parameters:
- name: product
in: query
@@ -2072,11 +2074,11 @@ paths:
- voice
- write
description: |-
- The product to retrieve source languages for. Supported values: `translate_text`, `translate_document`,
+ The product to retrieve languages for. Supported values: `translate_text`, `translate_document`,
`glossary`, `voice`, `write`.
responses:
200:
- description: JSON array where each item represents a supported source language.
+ description: JSON array where each item represents a supported language.
headers:
X-Trace-ID:
$ref: '#/components/headers/X-Trace-ID'
@@ -2089,109 +2091,30 @@ paths:
required:
- lang
- name
+ - usable_as_source
+ - usable_as_target
- features
properties:
lang:
- description: The language code of the given language.
+ description: The language code (BCP 47).
type: string
example: de
name:
description: Name of the language in English.
type: string
example: German
+ usable_as_source:
+ description: Whether this language can be used as a source language with the specified product.
+ type: boolean
+ usable_as_target:
+ description: Whether this language can be used as a target language with the specified product.
+ type: boolean
features:
description: |-
- Array of feature strings indicating capabilities supported for this language
- with the specified product.
- type: array
- items:
- type: string
- enum:
- - tag_handling
- - glossary
- example:
- - tag_handling
- - glossary
- examples:
- translateTextSources:
- summary: Source languages for text translation
- value:
- - lang: de
- name: German
- features:
- - tag_handling
- - glossary
- - lang: en
- name: English
- features:
- - tag_handling
- - glossary
- 400:
- $ref: '#/components/responses/BadRequest'
- 401:
- $ref: '#/components/responses/Unauthorized'
- 403:
- $ref: '#/components/responses/Forbidden'
- 429:
- $ref: '#/components/responses/TooManyRequests'
- 500:
- $ref: '#/components/responses/InternalServerError'
- 503:
- $ref: '#/components/responses/ServiceUnavailable'
- security:
- - auth_header: []
- /v3/languages/target:
- get:
- tags:
- - MetaInformation
- summary: Retrieve Target Languages
- operationId: getTargetLanguages
- description: |-
- Returns target languages supported by the specified DeepL API product.
- parameters:
- - name: product
- in: query
- required: true
- schema:
- type: string
- enum:
- - translate_text
- - translate_document
- - glossary
- - voice
- - write
- description: |-
- The product to retrieve target languages for. Supported values: `translate_text`, `translate_document`,
- `glossary`, `voice`, `write`.
- responses:
- 200:
- description: JSON array where each item represents a supported target language.
- headers:
- X-Trace-ID:
- $ref: '#/components/headers/X-Trace-ID'
- content:
- application/json:
- schema:
- type: array
- items:
- type: object
- required:
- - lang
- - name
- - features
- properties:
- lang:
- description: The language code of the given language.
- type: string
- example: en-US
- name:
- description: Name of the language in English.
- type: string
- example: English (American)
- features:
- description: |-
- Array of feature strings indicating capabilities supported for this language
- with the specified product.
+ Features supported for this language with the specified product. Always present;
+ empty array if no optional features are supported. Consult `/v3/languages/products`
+ 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
@@ -2207,24 +2130,29 @@ paths:
- tag_handling
- glossary
examples:
- translateTextTargets:
- summary: Target languages for text translation
+ translateTextLanguages:
+ summary: Languages for text translation
value:
- lang: de
name: German
+ usable_as_source: true
+ usable_as_target: true
features:
- formality
- tag_handling
- glossary
- - lang: en-US
- name: English (American)
+ - lang: en
+ name: English
+ usable_as_source: true
+ usable_as_target: false
features:
- tag_handling
- glossary
- - lang: fr
- name: French
+ - lang: en-US
+ name: English (American)
+ usable_as_source: false
+ usable_as_target: true
features:
- - formality
- tag_handling
- glossary
400:
diff --git a/docs.json b/docs.json
index 70e4ad9..e37a72c 100644
--- a/docs.json
+++ b/docs.json
@@ -200,8 +200,7 @@
"group": "Retrieve languages by product [BETA]",
"pages": [
"api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
- "api-reference/api-reference/retrieve-languages/retrieve-source-languages-beta",
- "api-reference/api-reference/retrieve-languages/retrieve-target-languages-beta",
+ "api-reference/api-reference/retrieve-languages/retrieve-languages-beta",
"api-reference/api-reference/retrieve-languages/retrieve-products-beta",
"api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta",
"api-reference/api-reference/retrieve-languages/migrate-from-v2-languages"
From e56d808c68febbc7b7b2067964ba1c066bc49063 Mon Sep 17 00:00:00 2001
From: Daniel Jones
Date: Wed, 11 Mar 2026 21:57:50 +0100
Subject: [PATCH 32/32] combine source and target
---
.../language-feature-use-cases-beta.mdx | 170 ++++++++++++++++++
docs.json | 1 +
2 files changed, 171 insertions(+)
create mode 100644 api-reference/api-reference/retrieve-languages/language-feature-use-cases-beta.mdx
diff --git a/api-reference/api-reference/retrieve-languages/language-feature-use-cases-beta.mdx b/api-reference/api-reference/retrieve-languages/language-feature-use-cases-beta.mdx
new file mode 100644
index 0000000..7c6ff9a
--- /dev/null
+++ b/api-reference/api-reference/retrieve-languages/language-feature-use-cases-beta.mdx
@@ -0,0 +1,170 @@
+---
+title: 'Common use cases [BETA]'
+description: "Pseudocode examples for common language and feature lookup patterns using the v3/languages endpoints."
+---
+
+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.
+
+For background on how features and feature dependency types work, see the
+[overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta).
+
+
+ The examples below do not account for language pair exceptions. For most integrations this is fine — exceptions
+ are rare and the API handles them gracefully by disabling the unsupported feature rather than failing. If you
+ need precise feature support for specific language pairs, see
+ [Handling language pair exceptions](#handling-language-pair-exceptions) at the end of this page.
+
+
+---
+
+## 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
+`usable_as_target` to populate each dropdown separately.
+
+```
+GET /v3/languages?product=translate_text
+
+languages = response
+
+source_options = languages.filter(l => l.usable_as_source)
+target_options = languages.filter(l => l.usable_as_target)
+
+render source_dropdown(source_options)
+render target_dropdown(target_options)
+```
+
+---
+
+## Show formality options only when supported
+
+`formality` is a target-only feature. Check the selected target language's `features` array — no need to look
+at the source language.
+
+```
+GET /v3/languages?product=translate_text
+
+languages = response
+target = languages.find(l => l.lang == selected_target_lang)
+
+if target.features.includes("formality"):
+ show formality_selector // e.g. ["default", "more", "less"]
+else:
+ hide formality_selector
+```
+
+---
+
+## Check if a glossary can be used for a given language pair
+
+`glossary` is a source-and-target feature — both languages must support it.
+
+```
+GET /v3/languages?product=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")
+```
+
+---
+
+## List target languages that accept glossaries from a given source language
+
+Filter to targets where both the source and target support the `glossary` feature.
+
+```
+GET /v3/languages?product=translate_text
+
+languages = response
+source_lang = "en"
+
+source = languages.find(l => l.lang == source_lang)
+
+if not source.features.includes("glossary"):
+ return [] // source doesn't support glossary at all
+
+targets_with_glossary = languages
+ .filter(l => l.usable_as_target)
+ .filter(l => l.features.includes("glossary"))
+```
+
+---
+
+## Show writing style options for the Write product
+
+`writing_style` is a target-only feature on the `write` product. Check the target language's `features` array.
+
+```
+GET /v3/languages?product=write
+
+languages = response
+target = languages.find(l => l.lang == selected_target_lang)
+
+if target.features.includes("writing_style"):
+ show writing_style_selector
+else:
+ hide writing_style_selector
+```
+
+---
+
+## Determine feature support programmatically
+
+Use `/v3/languages/products` to drive feature checks at runtime — without hardcoding which features are
+target-only or source-and-target into your client.
+
+```
+GET /v3/languages/products
+GET /v3/languages?product=translate_text
+
+products = first response
+languages = second response
+
+product = products.find(p => p.name == "translate_text")
+source = languages.find(l => l.lang == source_lang)
+target = languages.find(l => l.lang == target_lang)
+
+for feature in product.features:
+ supported = true
+ if feature.required_on_source and not source.features.includes(feature.name):
+ supported = false
+ if feature.required_on_target and not target.features.includes(feature.name):
+ supported = false
+```
+
+---
+
+## Handling language pair exceptions
+
+In rare cases, feature support for a specific pair differs from what the individual language objects indicate.
+The `/v3/languages/exceptions` endpoint exposes these cases. When an exception exists for a pair, its `features`
+array is authoritative — use it directly instead of intersecting the individual language `features` arrays.
+
+The example below shows a full glossary pair check that accounts for exceptions:
+
+```
+GET /v3/languages?product=translate_text
+GET /v3/languages/exceptions?product=translate_text
+
+languages = first response
+exceptions = second response
+
+exception = exceptions.find(e => e.source_lang == source_lang && e.target_lang == target_lang)
+
+if exception:
+ features = exception.features
+else:
+ source = languages.find(l => l.lang == source_lang)
+ target = languages.find(l => l.lang == target_lang)
+ features = intersect(source.features, target.features)
+
+glossary_allowed = features.includes("glossary")
+```
+
+The same pattern applies to any feature check — replace `"glossary"` with the feature you are checking.
diff --git a/docs.json b/docs.json
index e37a72c..1fb9a13 100644
--- a/docs.json
+++ b/docs.json
@@ -200,6 +200,7 @@
"group": "Retrieve languages by product [BETA]",
"pages": [
"api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta",
+ "api-reference/api-reference/retrieve-languages/language-feature-use-cases-beta",
"api-reference/api-reference/retrieve-languages/retrieve-languages-beta",
"api-reference/api-reference/retrieve-languages/retrieve-products-beta",
"api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta",