Skip to content

v3/languages updates #315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
daniel-jones-dev wants to merge 5 commits into
base: main
Choose a base branch
from
+76 −66
Open

v3/languages updates #315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f063452
docs(languages): record 22 April changes in changelog
daniel-jones-dev Apr 23, 2026
34d3561
docs(languages): show changelog entries newest-first
daniel-jones-dev Apr 23, 2026
eddce02
docs(languages): add style_rules product
daniel-jones-dev Apr 23, 2026
a1ee41d
docs(languages): add feature reference table to overview
daniel-jones-dev Apr 23, 2026
44e0292
docs(languages): add planned rename of custom_instructions feature
daniel-jones-dev Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions api-reference/languages/language-feature-use-cases.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,9 +145,9 @@ target = languages.find(l => l.lang == target_lang)

for feature in product.features:
supported = true
if feature.required_on_source and not source.features.includes(feature.name):
if feature.needs_source_support and not source.features.includes(feature.name):
supported = false
if feature.required_on_target and not target.features.includes(feature.name):
if feature.needs_target_support and not target.features.includes(feature.name):
supported = false
```

39 changes: 30 additions & 9 deletions api-reference/languages/retrieve-supported-languages-by-product.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ are querying language support for:
| `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 |

<Note>
`glossary` is a product value indicating glossaries can be created for that language, and managed via the glossary
Expand Down Expand Up @@ -128,12 +129,29 @@ To use a feature, one or both languages in the pair must support it. For example
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 features are also supported by the schema, and may be introduced in future products.
- **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.
Expand All @@ -150,25 +168,28 @@ curl -X GET 'https://api.deepl.com/v3/languages/products' \
[
{
"name": "translate_text",
"endpoints": ["v2/translate"],
"features": [
{
"name": "formality",
"required_on_target": true
"needs_target_support": true
},
{
"name": "custom_instructions",
"required_on_target": true
"needs_target_support": true
},
{
"name": "tag_handling",
"required_on_source": true,
"required_on_target": true
"needs_source_support": true,
"needs_target_support": true
},
{
"name": "glossary",
"required_on_source": true,
"required_on_target": true
"needs_source_support": true,
"needs_target_support": true
},
{
"name": "auto_detection",
"needs_source_support": true
}
]
}
Expand Down
58 changes: 29 additions & 29 deletions api-reference/languages/v3-languages-changelog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,24 @@ description: 'Changes and planned updates to the v3/languages endpoints during t

This section will list dated changes to the API since the initial beta release.

### 19 March 2026
### 22 April 2026

Initial beta release.
**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.

**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`).

### 17 April 2026

Expand All @@ -24,33 +39,13 @@ pairs where feature support differs from what can be predicted from the individu
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.

## Planned changes

The following changes are planned before general availability. They are not yet live.

---

### Breaking: rename `required_on_source` / `required_on_target`

The feature dependency flags on `/v3/languages/products` will be renamed:

| Current name | New name |
|---|---|
| `required_on_source` | `needs_source_support` |
| `required_on_target` | `needs_target_support` |

The semantics are unchanged — only the field names differ. Update any code that reads these fields.

*Reasoning*: "required" reads like a JSON schema constraint (mandatory field) rather than a language support check.

---
### 19 March 2026

### Breaking: remove `endpoints` from `/v3/languages/products`
Initial beta release.

The `endpoints` array will be removed from each product object in the `/v3/languages/products` response.
## Planned changes

*Reasoning*: endpoint information is not useful programmatically. The applicable endpoints will still be described in
the documentation for each product.
The following changes are planned before general availability. They are not yet live.

---

Expand All @@ -73,10 +68,15 @@ Possible values: `"beta"`, `"early_access"`. Languages in GA omit this field ent

---

### New: `auto_detection` feature across multiple products
### Breaking: rename `custom_instructions` feature to `style_rules`

The `custom_instructions` feature value on `translate_text` will be renamed to `style_rules`:

| Current value | New value |
|---|---|
| `custom_instructions` | `style_rules` |

An `auto_detection` feature will be added 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`).
Update any code that checks for `"custom_instructions"` in a language's `features` array.

---

Expand Down
41 changes: 15 additions & 26 deletions api-reference/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1970,10 +1970,10 @@ paths:
summary: Retrieve Language Products
operationId: getLanguageProducts
description: |-
Returns all DeepL API products, including the API endpoints they expose, and the features they support.
Returns all DeepL API products and the features they support.

For each feature, the response indicates which languages must support it for the feature to be
available — source only (`required_on_source`), target only (`required_on_target`), or both.
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`.
responses:
Expand All @@ -1990,7 +1990,6 @@ paths:
type: object
required:
- name
- endpoints
- features
properties:
name:
Expand All @@ -2004,13 +2003,6 @@ paths:
- write
- style_rules
example: translate_text
endpoints:
description: API endpoints associated with this product.
type: array
items:
type: string
example:
- v2/translate
features:
description: |-
Features supported by this product. Each feature indicates which languages
Expand All @@ -2031,37 +2023,34 @@ paths:
- glossary
- writing_style
- tone
required_on_source:
- auto_detection
needs_source_support:
description: If `true`, the source language must support this feature for it to be available. Defaults to `false` if absent.
type: boolean
required_on_target:
needs_target_support:
description: If `true`, the target language must support this feature for it to be available. Defaults to `false` if absent.
type: boolean
example:
- name: translate_text
endpoints:
- v2/translate
features:
- name: formality
required_on_target: true
needs_target_support: true
- name: custom_instructions
required_on_target: true
needs_target_support: true
- name: tag_handling
required_on_source: true
required_on_target: true
needs_source_support: true
needs_target_support: true
- name: glossary
required_on_source: true
required_on_target: true
needs_source_support: true
needs_target_support: true
- name: auto_detection
needs_source_support: true
- name: voice
endpoints:
- v3/voice/realtime
features:
- name: glossary
required_on_source: true
required_on_target: true
needs_source_support: true
needs_target_support: true
- name: style_rules
endpoints:
- v3/style_rules
features: []
400:
$ref: '#/components/responses/BadRequest'
Expand Down