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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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/19] 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