diff --git a/api-reference/languages/language-feature-use-cases.mdx b/api-reference/languages/language-feature-use-cases.mdx
index d7c8473..6cde5ee 100644
--- a/api-reference/languages/language-feature-use-cases.mdx
+++ b/api-reference/languages/language-feature-use-cases.mdx
@@ -5,20 +5,20 @@ description: "Pseudocode examples for common language and feature lookup pattern
---
This page shows how to use the `/v3/languages` endpoints for common integration tasks. Examples are written
-as pseudocode and are product-agnostic unless otherwise noted.
+as pseudocode and are resource-agnostic unless otherwise noted.
For background on how features and feature dependency types work, see the
-[overview](/api-reference/languages/retrieve-supported-languages-by-product).
+[overview](/api-reference/languages/retrieve-supported-languages-by-resource).
---
## Populate source and target language dropdowns
-A single call to `GET /v3/languages` returns all languages for a product. Filter by `usable_as_source` and
+A single call to `GET /v3/languages` returns all languages for a resource. Filter by `usable_as_source` and
`usable_as_target` to populate each dropdown separately.
```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
languages = response
@@ -34,15 +34,15 @@ render target_dropdown(target_options)
## Show formality options only when supported
`formality` only needs to be supported by the target language. Check the selected target language's `features`
-array — no need to look at the source language.
+object — no need to look at the source language.
```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
languages = response
target = languages.find(l => l.lang == selected_target_lang)
-if target.features.includes("formality"):
+if "formality" in target.features:
show formality_selector // e.g. ["default", "more", "less"]
else:
hide formality_selector
@@ -55,15 +55,15 @@ else:
`glossary` must be supported by both languages.
```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
languages = response
source = languages.find(l => l.lang == source_lang)
target = languages.find(l => l.lang == target_lang)
-glossary_allowed = source.features.includes("glossary")
- and target.features.includes("glossary")
+glossary_allowed = "glossary" in source.features
+ and "glossary" in target.features
```
---
@@ -73,34 +73,34 @@ glossary_allowed = source.features.includes("glossary")
Filter to targets where both the source and target support the `glossary` feature.
```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
languages = response
source_lang = "en"
source = languages.find(l => l.lang == source_lang)
-if not source.features.includes("glossary"):
+if "glossary" not in source.features:
return [] // source doesn't support glossary at all
targets_with_glossary = languages
.filter(l => l.usable_as_target)
- .filter(l => l.features.includes("glossary"))
+ .filter(l => "glossary" in l.features)
```
---
-## Show writing style options for the Write product
+## Show writing style options for the Write resource
-`writing_style` is a target-only feature on the `write` product. Check the target language's `features` array.
+`writing_style` is a target-only feature on the `write` resource. Check the target language's `features` object.
```
-GET /v3/languages?product=write
+GET /v3/languages?resource=write
languages = response
target = languages.find(l => l.lang == selected_target_lang)
-if target.features.includes("writing_style"):
+if "writing_style" in target.features:
show writing_style_selector
else:
hide writing_style_selector
@@ -110,12 +110,12 @@ else:
## Check if style rules are available for a target language
-Use `product=style_rules` to query which languages support style rules. Style rules are target-language only — check
-that the target language is listed in the response. The `style_rules` product has no additional features, so only
+Use `resource=style_rules` to query which languages support style rules. Style rules are target-language only — check
+that the target language is listed in the response. The `style_rules` resource has no additional features, so only
the language availability needs to be checked.
```
-GET /v3/languages?product=style_rules
+GET /v3/languages?resource=style_rules
languages = response
target = languages.find(l => l.lang == selected_target_lang)
@@ -130,25 +130,24 @@ else:
## Determine feature support programmatically
-Use `/v3/languages/products` to drive feature checks at runtime — without hardcoding which features need
+Use `/v3/languages/resources` to drive feature checks at runtime — without hardcoding which features need
target-only or both-language support into your client.
```
-GET /v3/languages/products
-GET /v3/languages?product=translate_text
+GET /v3/languages/resources
+GET /v3/languages?resource=translate_text
-products = first response
+resources = first response
languages = second response
-product = products.find(p => p.name == "translate_text")
+resource = resources.find(r => r.name == "translate_text")
source = languages.find(l => l.lang == source_lang)
target = languages.find(l => l.lang == target_lang)
-for feature in product.features:
+for feature in resource.features:
supported = true
- if feature.needs_source_support and not source.features.includes(feature.name):
+ if feature.needs_source_support and feature.name not in source.features:
supported = false
- if feature.needs_target_support and not target.features.includes(feature.name):
+ if feature.needs_target_support and feature.name not in target.features:
supported = false
```
-
diff --git a/api-reference/languages/migrate-from-v2-languages.mdx b/api-reference/languages/migrate-from-v2-languages.mdx
index 4b8036a..0c0e203 100644
--- a/api-reference/languages/migrate-from-v2-languages.mdx
+++ b/api-reference/languages/migrate-from-v2-languages.mdx
@@ -20,18 +20,18 @@ GET /v2/languages?type=source
GET /v2/languages?type=target
```
-v3 uses a single endpoint that returns all languages for a product, with each language indicating whether it is
+v3 uses a single endpoint that returns all languages for a resource, with each language indicating whether it is
usable as a source, a target, or both:
```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
```
-### New product identifiers
+### New resource 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 languages are implicitly tied to text and document translation. v3 introduces an explicit `resource` parameter that applies across all DeepL API resources:
-| v2 | v3 `product` value |
+| **v2** | **v3 `resource` value** |
|---|---|
| *(implicit, text/document translation only)* | `translate_text` |
| *(implicit, text/document translation only)* | `translate_document` |
@@ -43,16 +43,16 @@ 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 target languages include a boolean `supports_formality` field. v3 replaces this with a `features` object that covers additional capabilities per resource:
-| v2 field | v3 equivalent |
+| **v2 field** | **v3 equivalent** |
|---|---|
-| `"supports_formality": true` | `"features": ["formality"]` on the language object |
+| `"supports_formality": true` | `"formality"` key present in the language's `features` object |
For example, querying languages for text translation:
```sh
-curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
+curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
@@ -63,29 +63,39 @@ curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
"name": "German",
"usable_as_source": true,
"usable_as_target": true,
- "features": ["formality", "tag_handling", "glossary"]
+ "status": "stable",
+ "features": {
+ "formality": {"status": "stable"},
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
},
{
"lang": "en-US",
"name": "English (American)",
"usable_as_source": false,
"usable_as_target": true,
- "features": ["tag_handling", "glossary"]
+ "status": "stable",
+ "features": {
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
}
]
```
-The response indicates German supports `formality`, but English (American) does not.
+The response indicates German supports `formality` (key present in `features`), but English (American) does not (key absent).
-See the [overview](/api-reference/languages/retrieve-supported-languages-by-product) for the full list of features per product.
+See the [overview](/api-reference/languages/retrieve-supported-languages-by-resource) for the full list of features per resource.
### Response field names
-| v2 field | v3 field |
-|----------------------|------------------------|
-| `language` | `lang` |
-| `name` | `name` *(unchanged)* |
-| `supports_formality` | `features["formality]` |
+| **v2 field** | **v3 field** |
+|----------------------|---------------------------------------------------|
+| `language` | `lang` |
+| `name` | `name` *(unchanged)* |
+| `supports_formality` | `"formality"` key in `features` object |
+| *(not present)* | `status` |
### Language code casing
@@ -97,6 +107,6 @@ DeepL accepts language codes case-insensitively as input across all endpoints. H
If you currently use `/v2/glossary-language-pairs` to discover which language pairs are supported for glossaries, use one of the following:
-- `GET /v3/languages?product=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Filter by `usable_as_source` and `usable_as_target` as needed. Any combination of a valid source and target language is a supported glossary language pair.
-- `GET /v3/languages?product=translate_text` to check which languages support using a glossary during text translation. Languages that include `"glossary"` in their `features` array support the `glossary_id` parameter on the translate endpoint.
-- Similarly, use `product=translate_document` to check glossary support for document translation.
+- `GET /v3/languages?resource=glossary` to check which languages support glossary management (i.e. creating a glossary for that language). Filter by `usable_as_source` and `usable_as_target` as needed. Any combination of a valid source and target language is a supported glossary language pair.
+- `GET /v3/languages?resource=translate_text` to check which languages support using a glossary during text translation. Languages with a `"glossary"` key in their `features` object support the `glossary_id` parameter on the translate endpoint.
+- Similarly, use `resource=translate_document` to check glossary support for document translation.
diff --git a/api-reference/languages/retrieve-languages-by-product.mdx b/api-reference/languages/retrieve-languages-by-resource.mdx
similarity index 100%
rename from api-reference/languages/retrieve-languages-by-product.mdx
rename to api-reference/languages/retrieve-languages-by-resource.mdx
diff --git a/api-reference/languages/retrieve-products.mdx b/api-reference/languages/retrieve-products.mdx
index 97e68d1..51f8e10 100644
--- a/api-reference/languages/retrieve-products.mdx
+++ b/api-reference/languages/retrieve-products.mdx
@@ -1,9 +1,11 @@
---
-openapi: get /v3/languages/products
-title: "Retrieve language products"
+openapi: get /v3/languages/resources
+title: "Retrieve language resources"
tag: "BETA"
+description: "Learn how to retrieve the list of DeepL API resources and their supported language features."
---
This endpoint is available for testing in BETA. Breaking changes may be pushed with little or no advance notice, and we provide no guarantees of stability.
+
diff --git a/api-reference/languages/retrieve-supported-languages-by-product.mdx b/api-reference/languages/retrieve-supported-languages-by-product.mdx
deleted file mode 100644
index 2ff551e..0000000
--- a/api-reference/languages/retrieve-supported-languages-by-product.mdx
+++ /dev/null
@@ -1,224 +0,0 @@
----
-title: 'Retrieve supported languages by product'
-tag: "BETA"
-sidebarTitle: 'Overview'
-description: "API reference for retrieving supported languages with the DeepL API across all products."
----
-
-Get information about all currently supported languages across all DeepL API products.
-
-
- The `/v3/languages` endpoints provide a single source of truth for language and feature support across all DeepL
- 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/languages/migrate-from-v2-languages)
- for a full list of differences and code examples.
-
- **These endpoints are available for testing in BETA.** Breaking changes may be pushed with little or no advance
- notice, and we provide no guarantees of stability. Please do not use `/v3/languages` in production. See the
- [changelog](/api-reference/languages/v3-languages-changelog) for planned changes.
-
-
-We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:
-- [Retrieve languages](/api-reference/languages/retrieve-languages-by-product)
-- [Retrieve products](/api-reference/languages/retrieve-products)
-
-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).
-
-## Products list
-
-To retrieve language support, decide which DeepL product you're building for, then call `GET /v3/languages` with
-the appropriate `product` value. The `product` parameter is required and identifies which DeepL API product you
-are querying language support for:
-
-| Value | Description |
-|---|---|
-| `translate_text` | Text translation via the `/v2/translate` endpoint |
-| `translate_document` | Document translation via the `/v2/document` endpoint |
-| `voice` | Speech transcription and translation via the `/v3/voice` endpoints |
-| `write` | Text improvement via the `/v2/write` endpoints |
-| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
-| `style_rules` | Style rules management via the `/v3/style_rules`endpoints |
-
-
- `glossary` is a product value indicating glossaries can be created for that language, and managed via the glossary
- management endpoints.
-
- Support for glossaries within specific products (for example text translation) is indicated by the `glossary`
- feature value, explained in a later section.
-
-
-## Basic example
-
-Each language in the response includes a `features` array indicating which optional capabilities are available for that
-language — see the [Product features](#product-features) section below for details.
-
-The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update
-your requests to use `https://api-free.deepl.com` instead.
-
-The following example responses are truncated; the full API responses can include over 100 languages.
-
-
-
-
-```sh Example request: languages for text translation
-curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-
-
-```http Example request: languages for text translation
-GET /v3/languages?product=translate_text HTTP/2
-Host: api.deepl.com
-Authorization: DeepL-Auth-Key [yourAuthKey]
-User-Agent: YourApp/1.2.3
-```
-
-
-
-```json Example response
-[
- {
- "lang": "de",
- "name": "German",
- "usable_as_source": true,
- "usable_as_target": true,
- "features": [
- "formality",
- "tag_handling",
- "glossary"
- ]
- },
- {
- "lang": "en",
- "name": "English",
- "usable_as_source": true,
- "usable_as_target": false,
- "features": [
- "tag_handling",
- "glossary"
- ]
- },
- {
- "lang": "en-US",
- "name": "English (American)",
- "usable_as_source": false,
- "usable_as_target": true,
- "features": [
- "tag_handling",
- "glossary"
- ]
- }
-]
-```
-
-## Language codes
-
-Language codes in the `lang` field follow [BCP 47](https://www.rfc-editor.org/rfc/rfc5646). The base language
-subtag is always present; script, region, and variant subtags are included where needed to distinguish variants. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.
-
-## Product features
-
-Each language object includes a `features` array indicating which optional capabilities are supported for that language
-with the requested product.
-
-To use a feature, one or both languages in the pair must support it. For example, for text translation:
-
-- **Target-only**: `formality` only needs to be supported by the target language. Check that `"formality"` is
- present in the target language's `features` array.
-- **Source-and-target**: `tag_handling` and `glossary` must be supported by both languages. Check that the
- feature is present in *both* the source and target language's `features` arrays.
-- **Source-only**: `auto_detection` only needs to be supported by the source language.
-
-In the documentation for API features that are supported for only a subset of languages, we specify
-which language feature value to check, and whether to check the source language, target language, or both.
-
-### Product feature reference
-
-The table below lists all feature values that can appear in a language's `features` array.
-
-| Feature | Check language support on | Products | Description |
-|------------------------------|---------------------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. |
-| `custom_instructions` | target | `translate_text` | Language supports custom instructions that guide how DeepL translates text. |
-| `formality` | target | `translate_text`, `translate_document` | Language supports formality control — adjusting the output to use formal or informal register. |
-| `glossary` | source + target | `translate_text`, `translate_document`, `voice` | Language can be used with a glossary to enforce specific terminology. Both the source and target language must support this for a glossary to be usable with a given pair. |
-| `tag_handling` | source + target | `translate_text`, `translate_document` | Language supports tag-aware translation, preserving markup structure (e.g. HTML, XML) in the output. |
-| `transcription` | source | `voice` | Language supports transcription from audio to text. |
-| `transcription_external` | source | `voice` | Like `transcription`, but relies on using external service providers. |
-| `translated_speech` | target | `voice` | Language supports conversion from translated text to audio output. |
-| `translated_speech_external` | target | `voice` | Like `translated_speech`, but relies on using external service providers. |
-| `tone` | target | `write` | Language supports tone selection (e.g. confident, diplomatic, enthusiastic). |
-| `writing_style` | target | `write` | Language supports writing style selection (e.g. academic, casual, business). |
-
-## Retrieving products programmatically
-
-Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically.
-For each feature, the response indicates which languages must support it for the feature to be available —
-source only, target only, or both — allowing clients to determine feature availability for a language pair
-by checking the appropriate `features` arrays.
-
-```sh
-curl -X GET 'https://api.deepl.com/v3/languages/products' \
---header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
-```
-
-```json Example response (truncated)
-[
- {
- "name": "translate_text",
- "features": [
- {
- "name": "formality",
- "needs_target_support": true
- },
- {
- "name": "custom_instructions",
- "needs_target_support": true
- },
- {
- "name": "tag_handling",
- "needs_source_support": true,
- "needs_target_support": true
- },
- {
- "name": "glossary",
- "needs_source_support": true,
- "needs_target_support": true
- },
- {
- "name": "auto_detection",
- "needs_source_support": true
- }
- ]
- }
-]
-```
-
-## API stability
-
-The v3 language endpoints are designed to be forward-compatible:
-
-- New features may be added to the `features` array
-- New languages will be added as DeepL support expands
-- Existing fields will not be removed or changed in backwards-incompatible ways
-
-In rare cases, a language may be removed from the default response (for example, if it moves from stable
-to beta). When this happens, it will still be accessible via `?include=beta`. We aim to avoid this, but
-build your integration to handle languages disappearing from the response gracefully.
-
-
- Build your integration to gracefully handle new BCP 47 `lang` codes and new values in the `features` array. Do not hardcode assumptions about the format of language codes -- see [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.
-
-
-## Best practices
-
-1. **Cache responses**: Language support changes infrequently. Consider caching responses for up to 1 hour.
-
-2. **Check features**: Always check the `features` array on language objects rather than assuming support (e.g. for formality, glossary use, or writing style).
-
-3. **Handle forward compatibility**: New languages and features may be added at any time. Build your integration to dynamically accept new `lang` codes and `features` values instead of maintaining a hardcoded allowlist.
-
-4. **Use specific variants**: For target languages, prefer specific regional variants (e.g., `"en-US"`, `"en-GB"`) when the distinction matters to your users.
diff --git a/api-reference/languages/retrieve-supported-languages-by-resource.mdx b/api-reference/languages/retrieve-supported-languages-by-resource.mdx
new file mode 100644
index 0000000..55f3f7c
--- /dev/null
+++ b/api-reference/languages/retrieve-supported-languages-by-resource.mdx
@@ -0,0 +1,248 @@
+---
+title: 'Retrieve supported languages by resource'
+tag: "BETA"
+sidebarTitle: 'Overview'
+description: "Learn how to retrieve supported language and feature data across all DeepL API resources using the v3/languages endpoints."
+---
+
+Get information about all currently supported languages across all DeepL API resources.
+
+
+ These **BETA** endpoints replace `/v2/languages` and `/v2/glossary-language-pairs` (see the [migration guide](/api-reference/languages/migrate-from-v2-languages)). Do not use them in production; breaking changes may be pushed without advance notice (see the [changelog](/api-reference/languages/v3-languages-changelog)).
+
+
+We also provide auto-generated API specs from DeepL's OpenAPI file, for use with API clients and code generation tools:
+- [Retrieve languages](/api-reference/languages/retrieve-languages-by-resource)
+- [Retrieve resources](/api-reference/languages/retrieve-products)
+
+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).
+
+## Resources list
+
+To retrieve language support, decide which DeepL resource you're building for, then call `GET /v3/languages` with
+the appropriate `resource` value. The `resource` parameter is required and identifies which DeepL API resource you
+are querying language support for:
+
+| **Value** | **Description** |
+|---|---|
+| `translate_text` | Text translation via the `/v2/translate` endpoint |
+| `translate_document` | Document translation via the `/v2/document` endpoint |
+| `voice` | Speech transcription and translation via the `/v3/voice` endpoints |
+| `write` | Text improvement via the `/v2/write` endpoints |
+| `glossary` | Glossary management via the `/v2/` and `/v3/glossaries` endpoints |
+| `style_rules` | Style rules management via the `/v3/style_rules` endpoints |
+
+
+ `glossary` is a resource value indicating glossaries can be created for that language, and managed via the glossary
+ management endpoints.
+
+ Support for glossaries within specific resources (for example text translation) is indicated by the `glossary`
+ feature value, explained in a later section.
+
+
+## Basic example
+
+Each language in the response includes a `features` object indicating which optional capabilities are available for that
+language — see the [Resource features](#resource-features) section below for details.
+
+The examples below use our API Pro endpoint `https://api.deepl.com`. If you're an API Free user, remember to update
+your requests to use `https://api-free.deepl.com` instead.
+
+The following example responses are truncated; the full API responses can include over 100 languages.
+
+
+
+
+```sh Example request: languages for text translation
+curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+
+
+```http Example request: languages for text translation
+GET /v3/languages?resource=translate_text HTTP/2
+Host: api.deepl.com
+Authorization: DeepL-Auth-Key [yourAuthKey]
+User-Agent: YourApp/1.2.3
+```
+
+
+
+```json Example response
+[
+ {
+ "lang": "de",
+ "name": "German",
+ "usable_as_source": true,
+ "usable_as_target": true,
+ "status": "stable",
+ "features": {
+ "formality": {"status": "stable"},
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
+ },
+ {
+ "lang": "en",
+ "name": "English",
+ "usable_as_source": true,
+ "usable_as_target": false,
+ "status": "stable",
+ "features": {
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
+ },
+ {
+ "lang": "en-US",
+ "name": "English (American)",
+ "usable_as_source": false,
+ "usable_as_target": true,
+ "status": "stable",
+ "features": {
+ "tag_handling": {"status": "stable"},
+ "glossary": {"status": "stable"}
+ }
+ }
+]
+```
+
+## Language codes
+
+Language codes in the `lang` field follow [BCP 47](https://www.rfc-editor.org/rfc/rfc5646). The base language
+subtag is always present; script, region, and variant subtags are included where needed to distinguish variants. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.
+
+## Resource features
+
+Each language object includes a `features` object indicating which optional capabilities are supported for that language
+with the requested resource. Each key is a feature name; the value is an object with at least a `status` field.
+
+To check whether a feature is supported, check that the key exists in the `features` object:
+
+```text
+// Feature supported:
+"features": { "formality": { "status": "stable" } }
+
+// Feature not supported:
+"features": {}
+```
+
+To use a feature, one or both languages in the pair must support it. For example, for text translation:
+
+- **Target-only**: `formality` only needs to be supported by the target language. Check that `"formality"` is
+ a key in the target language's `features` object.
+- **Source-and-target**: `tag_handling` and `glossary` must be supported by both languages. Check that the
+ feature key is present in *both* the source and target language's `features` objects.
+- **Source-only**: `auto_detection` only needs to be supported by the source language.
+
+In the documentation for API features that are supported for only a subset of languages, we specify
+which language feature key to check, and whether to check the source language, target language, or both.
+
+### Resource feature reference
+
+The table below lists all feature keys that can appear in a language's `features` object.
+
+| **Feature** | **Check language support on** | **Resources** | **Description** |
+|------------------------------|---------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. |
+| `style_rules` | target | `translate_text` | Language supports style rules that guide how DeepL translates text. Used with the `custom_instructions` and `style_id` parameters on the translate endpoint. |
+| `formality` | target | `translate_text`, `translate_document` | Language supports formality control — adjusting the output to use formal or informal register. |
+| `glossary` | source + target | `translate_text`, `translate_document`, `voice` | Language can be used with a glossary to enforce specific terminology. Both the source and target language must support this for a glossary to be usable with a given pair. |
+| `tag_handling` | source + target | `translate_text`, `translate_document` | Language supports tag-aware translation, preserving markup structure (e.g. HTML, XML) in the output. |
+| `transcription` | source | `voice` | Language supports transcription from audio to text. |
+| `transcription_external` | source | `voice` | Like `transcription`, but relies on external service providers. |
+| `translated_speech` | target | `voice` | Language supports conversion from translated text to audio output. |
+| `translated_speech_external` | target | `voice` | Like `translated_speech`, but relies on external service providers. |
+| `tone` | target | `write` | Language supports tone selection (e.g. confident, diplomatic, enthusiastic). |
+| `writing_style` | target | `write` | Language supports writing style selection (e.g. academic, casual, business). |
+
+## Filtering by availability
+
+By default, `GET /v3/languages` returns only stable languages and features. Use the `include` query parameter
+to request additional languages and features based on their availability status:
+
+| **Value** | **Effect** |
+|---|---|
+| `beta` | Includes languages and features in beta, in addition to stable |
+| `external` | Includes features that rely on third-party service providers |
+
+Values can be combined with repeated parameters: `?include=beta&include=external`.
+
+The `status` field on each language object and each feature object indicates its availability:
+
+| **Status** | **Meaning** |
+|---|---|
+| `stable` | Generally available |
+| `beta` | Available for testing; may change |
+| `early_access` | Limited availability; may change |
+
+## Retrieving resources programmatically
+
+Use the `/v3/languages/resources` endpoint to retrieve the list of resources and their features programmatically.
+For each feature, the response indicates which languages must support it for the feature to be available —
+source only, target only, or both — allowing clients to determine feature availability for a language pair
+by checking the appropriate `features` objects.
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages/resources' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (truncated)
+[
+ {
+ "name": "translate_text",
+ "features": [
+ {
+ "name": "formality",
+ "needs_target_support": true
+ },
+ {
+ "name": "style_rules",
+ "needs_target_support": true
+ },
+ {
+ "name": "tag_handling",
+ "needs_source_support": true,
+ "needs_target_support": true
+ },
+ {
+ "name": "glossary",
+ "needs_source_support": true,
+ "needs_target_support": true
+ },
+ {
+ "name": "auto_detection",
+ "needs_source_support": true
+ }
+ ]
+ }
+]
+```
+
+## API stability
+
+The v3 language endpoints are designed to be forward-compatible:
+
+- New feature keys may be added to the `features` object
+- New languages will be added as DeepL support expands
+- Existing fields will not be removed or changed in backwards-incompatible ways
+
+In rare cases, a language may be removed from the default response (for example, if it moves from stable
+to beta). When this happens, it will still be accessible via `?include=beta`. We aim to avoid this, but
+build your integration to handle languages disappearing from the response gracefully.
+
+
+ Build your integration to gracefully handle new BCP 47 `lang` codes and new feature keys in the `features` object. Do not hardcode assumptions about the format of language codes. See [Language codes follow BCP 47](/docs/resources/language-release-process#language-codes-follow-bcp-47) for details.
+
+
+## Best practices
+
+1. **Cache responses**: Language support changes infrequently. Consider caching responses for up to 1 hour.
+
+2. **Check features**: Always check the `features` object on language objects rather than assuming support (e.g. for formality, glossary use, or writing style).
+
+3. **Handle forward compatibility**: New languages and features may be added at any time. Build your integration to dynamically accept new `lang` codes and new keys in the `features` object instead of maintaining a hardcoded allowlist.
+
+4. **Use specific variants**: For target languages, prefer specific regional variants (e.g., `"en-US"`, `"en-GB"`) when the distinction matters to your users.
diff --git a/api-reference/languages/v3-languages-changelog.mdx b/api-reference/languages/v3-languages-changelog.mdx
index 9d54647..2cf7f2f 100644
--- a/api-reference/languages/v3-languages-changelog.mdx
+++ b/api-reference/languages/v3-languages-changelog.mdx
@@ -12,89 +12,32 @@ description: 'Changes and planned updates to the v3/languages endpoints during t
## Changes since the initial beta release
-This section will list dated changes to the API since the initial beta release.
+This section lists dated changes to the API since the initial beta release.
-### 22 April 2026
-
-**Breaking: renamed `required_on_source` / `required_on_target`** — the feature dependency flags on
-`/v3/languages/products` have been renamed:
-
-| Old name | New name |
-|---|---|
-| `required_on_source` | `needs_source_support` |
-| `required_on_target` | `needs_target_support` |
-
-Semantics are unchanged. Update any code that reads these fields.
+### 5 May 2026
-**Breaking: removed `endpoints` from `/v3/languages/products`** — the `endpoints` array has been removed
-from each product object. The applicable endpoints are still described in the documentation for each product.
-
-**New: `auto_detection` feature** — a new `auto_detection` feature has been added across multiple products
-to indicate whether a language can be auto-detected as the source. This is a source-only feature
-(`needs_source_support: true`, `needs_target_support: false`).
+**Breaking: renamed `product` to `resource`** — the `product` query parameter on `GET /v3/languages` has been
+renamed to `resource`. The `/v3/languages/products` endpoint has been renamed to `/v3/languages/resources`.
+Update all calls accordingly.
-### 17 April 2026
-
-**Removed: `/v3/languages/exceptions`** — this endpoint has been removed. We no longer have any language
-pairs where feature support differs from what can be predicted from the individual language objects, so
-the endpoint had no data to return. Remove any calls to this endpoint; the per-language `features` arrays
-from `GET /v3/languages` are sufficient to determine feature support for all pairs.
-
-### 19 March 2026
-
-Initial beta release.
-
-## Planned changes
-
-The following changes are planned before general availability. They are not yet live.
-
----
-
-### New: language `status` field
-
-Language objects will include a `status` field indicating availability:
-
-```json
-{
- "lang": "xyz",
- "name": "Example Language",
- "usable_as_source": true,
- "usable_as_target": true,
- "features": [],
- "status": "stable"
-}
-```
-
-Possible values: `"stable"`, `"beta"`, `"early_access"`.
-
----
-
-### Breaking: `features` array replaced by dictionary
-
-The `features` property on languages will change from a list of strings to an object (dictionary). Each
-key is a feature name; the value is an object with at least a `status` field.
+**Breaking: `features` array replaced by object** — the `features` property on language objects has changed
+from an array of strings to an object (dictionary). Each key is a feature name; the value is an object with
+at least a `status` field.
Instead of:
```json
{
"lang": "de",
- "name": "German",
- ...
- "features": [
- "formality",
- "tag_handling"
- ]
+ "features": ["formality", "tag_handling"]
}
```
-the following schema will be used:
+the following schema is used:
```json
{
"lang": "de",
- "name": "German",
- ...
"features": {
"formality": {"status": "stable"},
"tag_handling": {"status": "stable"}
@@ -102,55 +45,72 @@ the following schema will be used:
}
```
-Feature objects may include additional fields beyond `status` in a future update. To check whether a feature is
-supported for a language, check that the key exists in the `features` object.
+To check whether a feature is supported, check that the key exists in the `features` object.
----
+**New: language `status` field** — language objects now include a `status` field indicating availability:
-### New: `include` query parameter
+```json
+{
+ "lang": "de",
+ "status": "stable",
+ "features": { ... }
+}
+```
-`GET /v3/languages` will accept a new `include` query parameter. By default (no parameter), only
-generally available languages and features are returned. The parameter accepts the following values:
+Possible values: `"stable"`, `"beta"`, `"early_access"`.
-| Value | Effect |
+**New: `include` query parameter** — `GET /v3/languages` now accepts an `include` query parameter.
+By default (no parameter), only stable languages and features are returned.
+
+| **Value** | **Effect** |
|---|---|
| `beta` | Includes languages and features in beta, in addition to stable |
-| `early_access` | Includes languages and features in early access and beta, in addition to stable |
-| `external` | Includes features that rely on external providers (orthogonal to stability level) |
+| `external` | Includes features that rely on third-party service providers |
Values are composable via repeated parameters: `?include=beta&include=external`.
-This parameter also controls whether beta and external features appear in the `features` dictionary — see the
-`features` schema change above.
-
----
+**Breaking: renamed `custom_instructions` feature to `style_rules`** — the `custom_instructions` feature
+value returned by `GET /v3/languages` has been renamed to `style_rules`:
-### Breaking: rename `product` to `resource`
-
-`resource` is a clearer name for what this is describing.
+| **Old value** | **New value** |
+|---|---|
+| `custom_instructions` | `style_rules` |
-This involves the following changes:
-- move the `GET /v3/languages/products` endpoint to `GET /v3/languages/resources`
-- rename the `GET /v3/languages` query parameter `product` to `resource`
+This affects the `features` object returned per language and the feature list returned by
+`GET /v3/languages/resources`. Note: the `custom_instructions` parameter on the translate endpoint
+is not affected by this change.
---
-### Breaking: rename `custom_instructions` feature to `style_rules`
+### 22 April 2026
-The `custom_instructions` feature value on `translate_text` will be renamed to `style_rules`:
+**Breaking: renamed `required_on_source` / `required_on_target`** — the feature dependency flags on
+`/v3/languages/products` have been renamed:
-| Current value | New value |
+| **Old name** | **New name** |
|---|---|
-| `custom_instructions` | `style_rules` |
+| `required_on_source` | `needs_source_support` |
+| `required_on_target` | `needs_target_support` |
-Update any code that checks for `"custom_instructions"` in a language's `features` array.
+Semantics are unchanged. Update any code that reads these fields.
----
+**Breaking: removed `endpoints` from `/v3/languages/products`** — the `endpoints` array has been removed
+from each product object. The applicable endpoints are still described in the documentation for each product.
-### New: expanded Voice features
+**New: `auto_detection` feature** — a new `auto_detection` feature has been added across multiple products
+to indicate whether a language can be auto-detected as the source. This is a source-only feature
+(`needs_source_support: true`, `needs_target_support: false`).
-The `voice` product will expose a richer set of features in `/v3/languages/products` and per-language `features` arrays,
-details are still being worked out.
+### 17 April 2026
+
+**Removed: `/v3/languages/exceptions`** — this endpoint has been removed. We no longer have any language
+pairs where feature support differs from what can be predicted from the individual language objects, so
+the endpoint had no data to return. Remove any calls to this endpoint; the per-language `features` objects
+from `GET /v3/languages` are sufficient to determine feature support for all pairs.
+
+### 19 March 2026
+
+Initial beta release.
---
@@ -164,4 +124,4 @@ These are under consideration and may or may not land before GA.
## Current beta state
-For the current API contract, see the [overview](/api-reference/languages/retrieve-supported-languages-by-product) and the auto-generated reference pages linked there.
+For the current API contract, see the [overview](/api-reference/languages/retrieve-supported-languages-by-resource) and the auto-generated reference pages linked there.
diff --git a/api-reference/openapi.json b/api-reference/openapi.json
index e782eac..1b26bcc 100644
--- a/api-reference/openapi.json
+++ b/api-reference/openapi.json
@@ -6586,7 +6586,7 @@
},
"SourceLanguage": {
"type": "string",
- "description": "Language of the text to be translated. If this parameter is omitted, the API will attempt to\ndetect the language of the text and translate it.\n\nFor the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).",
+ "description": "Language of the text to be translated. If this parameter is omitted, the API will attempt to\ndetect the language of the text and translate it.\n\nFor the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).",
"example": "EN"
},
"TranslationMemory": {
@@ -6760,7 +6760,7 @@
},
"TargetLanguage": {
"type": "string",
- "description": "The language into which the text should be translated.\n\nFor the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).",
+ "description": "The language into which the text should be translated.\n\nFor the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).",
"example": "DE"
},
"TargetLanguageWrite": {
diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml
index 7f25622..2567c3f 100644
--- a/api-reference/openapi.yaml
+++ b/api-reference/openapi.yaml
@@ -1966,21 +1966,21 @@ paths:
$ref: '#/components/responses/TooManyRequests'
security:
- auth_header: [ ]
- /v3/languages/products:
+ /v3/languages/resources:
get:
tags:
- MetaInformation
- beta
x-beta: true
- summary: Retrieve Language Products
- operationId: getLanguageProducts
+ summary: Retrieve Language Resources
+ operationId: getLanguageResources
description: |-
- Returns all DeepL API products and the features they support.
+ Returns all DeepL API resources and the features they support.
For each feature, the response indicates which languages must support it for the feature to be
available — source only (`needs_source_support`), target only (`needs_target_support`), or both.
This allows clients to determine feature availability for a language pair by checking the
- appropriate language's `features` array returned by `GET /v3/languages`.
+ appropriate language's `features` object returned by `GET /v3/languages`.
responses:
200:
description: JSON array where each item represents a DeepL API product.
@@ -1998,7 +1998,7 @@ paths:
- features
properties:
name:
- description: The product identifier.
+ description: The resource identifier.
type: string
enum:
- translate_text
@@ -2010,7 +2010,7 @@ paths:
example: translate_text
features:
description: |-
- Features supported by this product. Each feature indicates which languages
+ Features supported by this resource. Each feature indicates which languages
must support it for the feature to be available — source, target, or both.
type: array
items:
@@ -2019,11 +2019,11 @@ paths:
- name
properties:
name:
- description: The feature identifier, corresponding to values in the `features` array returned by `GET /v3/languages`.
+ description: The feature identifier, corresponding to keys in the `features` object returned by `GET /v3/languages`.
type: string
enum:
- formality
- - custom_instructions
+ - style_rules
- tag_handling
- glossary
- writing_style
@@ -2040,7 +2040,7 @@ paths:
features:
- name: formality
needs_target_support: true
- - name: custom_instructions
+ - name: style_rules
needs_target_support: true
- name: tag_handling
needs_source_support: true
@@ -2080,11 +2080,11 @@ paths:
summary: Retrieve Languages
operationId: getLanguages
description: |-
- Returns languages supported by the specified DeepL API product. Each language indicates whether it can
+ Returns languages supported by the specified DeepL API resource. Each language indicates whether it can
be used as a source language, a target language, or both, along with the features it supports for that
- product.
+ resource.
parameters:
- - name: product
+ - name: resource
in: query
required: true
schema:
@@ -2098,8 +2098,27 @@ paths:
- style_rules
example: translate_text
description: |-
- The product to retrieve languages for. Supported values: `translate_text`, `translate_document`,
+ The resource to retrieve languages for. Supported values: `translate_text`, `translate_document`,
`glossary`, `voice`, `write`, `style_rules`.
+ - name: include
+ in: query
+ required: false
+ schema:
+ type: array
+ items:
+ type: string
+ enum:
+ - beta
+ - external
+ style: form
+ explode: true
+ description: |-
+ Controls which languages and features are included in the response. By default, only stable
+ languages and features are returned. Values can be combined with repeated parameters
+ (e.g. `?include=beta&include=external`).
+
+ - `beta`: Include languages and features in beta, in addition to stable
+ - `external`: Include features that rely on third-party service providers
responses:
200:
description: JSON array where each item represents a supported language.
@@ -2118,6 +2137,7 @@ paths:
- usable_as_source
- usable_as_target
- features
+ - status
properties:
lang:
description: The language code (BCP 47).
@@ -2128,31 +2148,46 @@ paths:
type: string
example: German
usable_as_source:
- description: Whether this language can be used as a source language with the specified product.
+ description: Whether this language can be used as a source language with the specified resource.
type: boolean
usable_as_target:
- description: Whether this language can be used as a target language with the specified product.
+ description: Whether this language can be used as a target language with the specified resource.
type: boolean
+ status:
+ description: Availability status of this language.
+ type: string
+ enum:
+ - stable
+ - beta
+ - early_access
+ example: stable
features:
description: |-
- Features supported for this language with the specified product. Always present;
- empty array if no optional features are supported. Consult `/v3/languages/products`
+ Features supported for this language with the specified resource. Always present;
+ empty object if no optional features are supported. Each key is a feature name;
+ the value is an object with at least a `status` field. Consult `GET /v3/languages/resources`
to determine whether a feature must be present on the source language, target language,
- or both for a given product.
- type: array
- items:
- type: string
- enum:
- - formality
- - custom_instructions
- - tag_handling
- - glossary
- - writing_style
- - tone
+ or both for a given resource.
+ type: object
+ additionalProperties:
+ type: object
+ required:
+ - status
+ properties:
+ status:
+ description: Availability status of this feature for this language.
+ type: string
+ enum:
+ - stable
+ - beta
+ - early_access
example:
- - formality
- - tag_handling
- - glossary
+ formality:
+ status: stable
+ tag_handling:
+ status: stable
+ glossary:
+ status: stable
examples:
translateTextLanguages:
summary: Languages for text translation
@@ -2161,24 +2196,34 @@ paths:
name: German
usable_as_source: true
usable_as_target: true
+ status: stable
features:
- - formality
- - tag_handling
- - glossary
+ formality:
+ status: stable
+ tag_handling:
+ status: stable
+ glossary:
+ status: stable
- lang: en
name: English
usable_as_source: true
usable_as_target: false
+ status: stable
features:
- - tag_handling
- - glossary
+ tag_handling:
+ status: stable
+ glossary:
+ status: stable
- lang: en-US
name: English (American)
usable_as_source: false
usable_as_target: true
+ status: stable
features:
- - tag_handling
- - glossary
+ tag_handling:
+ status: stable
+ glossary:
+ status: stable
400:
$ref: '#/components/responses/BadRequest'
401:
@@ -4913,7 +4958,7 @@ components:
Language of the text to be translated. If this parameter is omitted, the API will attempt to
detect the language of the text and translate it.
- For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).
+ For the full list of supported source languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).
example: EN
TranslationMemory:
type: object
@@ -5085,7 +5130,7 @@ components:
description: |-
The language into which the text should be translated.
- For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-product) (beta).
+ For the full list of supported target languages, see [supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) or query the [`GET /v3/languages` endpoint](https://developers.deepl.com/api-reference/languages/retrieve-supported-languages-by-resource) (beta).
example: DE
TargetLanguageWrite:
type: string
diff --git a/docs.json b/docs.json
index 47aa9a4..1a886ff 100644
--- a/docs.json
+++ b/docs.json
@@ -250,12 +250,12 @@
"api-reference/languages",
"api-reference/languages/retrieve-supported-languages",
{
- "group": "Languages By Product",
+ "group": "Languages By Resource",
"tag": "BETA",
"pages": [
- "api-reference/languages/retrieve-supported-languages-by-product",
+ "api-reference/languages/retrieve-supported-languages-by-resource",
"api-reference/languages/language-feature-use-cases",
- "api-reference/languages/retrieve-languages-by-product",
+ "api-reference/languages/retrieve-languages-by-resource",
"api-reference/languages/retrieve-products",
"api-reference/languages/migrate-from-v2-languages",
"api-reference/languages/v3-languages-changelog"
@@ -351,6 +351,14 @@
}
},
"redirects": [
+ {
+ "source": "/api-reference/languages/retrieve-supported-languages-by-product",
+ "destination": "/api-reference/languages/retrieve-supported-languages-by-resource"
+ },
+ {
+ "source": "/api-reference/languages/retrieve-languages-by-product",
+ "destination": "/api-reference/languages/retrieve-languages-by-resource"
+ },
{
"source": "/docs/api-reference/improve-text/openapi-spec-for-text-improvement",
"destination": "/api-reference/improve-text/request-text-improvement"