You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(supported-languages): SupportedLanguages snippet over vended responses
Adds a single `<SupportedLanguages>` snippet that renders DeepL's
supported-languages information in MDX, drawn directly from the vended
/v3/languages responses. Doc authors drop the component anywhere they
would have hand-typed a language list and pass props that match the
API contract:
- `mode`: `inline` (default, comma-separated codes) | `bullets`
(vertical list with the language name) | `table` (the existing
interactive table on /docs/getting-started/supported-languages).
- `resource`: matches a /v3/languages resource name
(`translate_text`, `translate_document`, `voice`, `write`,
`glossary`, `style_rules`, `translation_memory`). Required for the
inline and bullets modes.
- `feature`: API feature key to filter by, exactly as it appears in
the `features` object of a response (snake_case).
- `direction`: `source` | `target`.
- `includeBeta`: include non-stable languages in the list.
Mintlify snippets are sandboxed and do not honour ES module imports,
so the per-resource JSON responses have to ship inline. The data
block lives between `// BEGIN GENERATED` / `// END GENERATED` markers
and is regenerated by `scripts/fetch_v3_languages.py`.
Script + workflow
- Folds the previous `scripts/generate_language_table.py` into
`scripts/fetch_v3_languages.py`. One script now fetches every
/v3/languages response and regenerates the inline data; the hourly
refresh workflow runs just that script.
- Adds retry-with-backoff for transient API failures (429, 5xx, and
network errors), honouring Retry-After when present.
- Validates response schemas before writing them (`resources` is a
list of objects with non-empty string `name`; each per-resource
response is a list of objects with non-empty string `lang` and
`name`). A schema mismatch raises with the exact path so a workflow
failure is actionable.
- Hard-fails if the snippet file or its BEGIN/END markers are missing.
- Discovers per-resource JSON files by walking `data/v3-languages/`,
so new resources (and manual stand-in files) appear in the snippet
automatically.
Data
- Vends a manually-maintained `data/v3-languages/translation_memory.json`
shaped like a /v3/languages response. Translation Memory is not yet
exposed by the API; once it is, the fetcher overwrites this file
with the real response and no other code has to change.
- Documents the same pattern in `data/v3-languages/README.md` as a
general "stand-in files for APIs not yet in /v3/languages" recipe.
- Picks up an API drift: `auto_detection` is now reported on
translate_document, and the new voice `spoken_terms` resource
feature is present.
MDX migrations
Replaces hand-typed language lists with the component in:
- `api-reference/improve-text.mdx` — `target_lang`, `writing_style`,
`tone` ParamFields.
- `api-reference/style-rules.mdx` — POST `language` ParamField.
- `api-reference/translate.mdx` — `formality` and
`custom_instructions` ParamFields.
- `api-reference/document.mdx` — `formality` ParamField.
- `docs/best-practices/custom-instructions.mdx` — technical
constraints "Supported target languages" bullet.
- `docs/getting-started/supported-languages.mdx` — the main table.
Each migrated list reflects the live API and includes regional
variants and beta states that the prior hand-typed lists missed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The document translation API allows you to translate whole documents and supports the following file types and extensions:
8
10
9
11
*`docx` / `doc` - Microsoft Word Document
@@ -146,7 +148,11 @@ These examples are for demonstration purposes only. In production code, the auth
146
148
The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition.
147
149
</ParamField>
148
150
<ParamFieldbody="formality"type="string">
149
-
Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages `DE` (German), `FR` (French), `IT` (Italian), `ES` (Spanish), `NL` (Dutch), `PL` (Polish), `PT-BR` and `PT-PT` (Portuguese), `JA` (Japanese), and `RU` (Russian). Learn more about the plain/polite feature for Japanese <ahref="https://support.deepl.com/hc/en-us/articles/6306700061852-About-the-plain-polite-feature-in-Japanese">here</a>. Setting this parameter with a target language that does not support formality will fail, unless one of the `prefer_...` options are used. To check formality support dynamically, call <ahref="/api-reference/languages/retrieve-supported-languages-by-resource"><code>GET /v3/languages?resource=translate_document</code></a> and look for the <code>formality</code> feature key on the target language. Possible options are:
151
+
Sets whether the translated text should lean towards formal or informal language. Currently supported for the following target languages:
Learn more about the plain/polite feature for Japanese <ahref="https://support.deepl.com/hc/en-us/articles/6306700061852-About-the-plain-polite-feature-in-Japanese">here</a>. Setting this parameter with a target language that does not support formality will fail, unless one of the `prefer_...` options are used. To check formality support dynamically, call <ahref="/api-reference/languages/retrieve-supported-languages-by-resource"><code>GET /v3/languages?resource=translate_document</code></a> and look for the <code>formality</code> feature key on the target language. Possible options are:
You can also retrieve supported languages programmatically via <ahref="/api-reference/languages/retrieve-supported-languages-by-resource"><code>GET /v3/languages?resource=write</code></a>.
80
73
@@ -100,15 +93,14 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
100
93
</Expandable>
101
94
Currently supported for the following target languages:
102
95
103
-
*`de` (German)
104
-
*`en-GB` (British English)
105
-
*`en-US` (American English)
106
-
*`es` (Spanish)
107
-
*`fr` (French)
108
-
*`it` (Italian)
109
-
*`pt-BR` (Brazilian Portuguese)
110
-
*`pt-PT` (Portuguese)
111
-
96
+
*`de` (German)
97
+
*`en-GB` (British English)
98
+
*`en-US` (American English)
99
+
*`es` (Spanish)
100
+
*`fr` (French)
101
+
*`it` (Italian)
102
+
*`pt-BR` (Brazilian Portuguese)
103
+
*`pt-PT` (Portuguese)
112
104
113
105
Styles prefixed with `prefer_` will fall back to the `default` style when used with a language that does not support styles (this is recommended for cases where no `target_lang` is set), the non-prefixed writing styles (except `default`) will return a HTTP 400 error in that case.
114
106
@@ -135,14 +127,14 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
135
127
136
128
Currently supported for the following target languages:
137
129
138
-
*`de` (German)
139
-
*`en-GB` (British English)
140
-
*`en-US` (American English)
141
-
*`es` (Spanish)
142
-
*`fr` (French)
143
-
*`it` (Italian)
144
-
*`pt-BR` (Brazilian Portuguese)
145
-
*`pt-PT` (Portuguese)
130
+
*`de` (German)
131
+
*`en-GB` (British English)
132
+
*`en-US` (American English)
133
+
*`es` (Spanish)
134
+
*`fr` (French)
135
+
*`it` (Italian)
136
+
*`pt-BR` (Brazilian Portuguese)
137
+
*`pt-PT` (Portuguese)
146
138
147
139
Tones prefixed with `prefer_` will fall back to the `default` tone when used with a language that does not support tones (this is recommended for cases where no `target_lang` is set), the non-prefixed tones (except `default`) will return a HTTP 400 error in that case.
The Style Rules API is currently available only to Pro API subscribers.
9
11
</Info>
@@ -161,7 +163,9 @@ Create a new style rule list with configured rules and optional custom instructi
161
163
The name of the style rule list. Maximum length: 1024 characters.
162
164
</ParamField>
163
165
<ParamFieldbody="language"type="string"required>
164
-
The target language for the style rules. Supported values: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`.
166
+
The target language for the style rules. Supported values:
167
+
168
+
<SupportedLanguagesresource="style_rules" />
165
169
</ParamField>
166
170
<ParamFieldbody="configured_rules"type="object">
167
171
An object containing predefined rules to enable for the style rule list. Rules are organized by category (e.g., `dates_and_times`, `punctuation`). Each category can contain multiple rule options.
The text-translation API currently consists of a single endpoint, `translate`, which is described below.
9
11
10
12
For highest translation quality, we recommend using our next-gen models. For details, please see [here](/api-reference/translate#about-the-model_type-parameter).
@@ -267,7 +269,11 @@ error.
267
269
</Info>
268
270
</ParamField>
269
271
<ParamFieldbody="formality"type="string">
270
-
Sets whether the translated text should lean towards formal or informal language. This feature currently only works for target languages <code>DE</code> (German), <code>FR</code> (French), <code>IT</code> (Italian), <code>ES</code> (Spanish), <code>ES-419</code> (Latin American Spanish), <code>NL</code> (Dutch), <code>PL</code> (Polish), <code>PT-BR</code> and <code>PT-PT</code> (Portuguese), <code>JA</code> (Japanese), and <code>RU</code> (Russian). Learn more about the <ahref="https://support.deepl.com/hc/en-us/articles/6306700061852-About-formality-plain-and-polite-tones-in-Japanese">plain/polite feature for Japanese ↗️</a>. To check formality support dynamically, call <ahref="/api-reference/languages/retrieve-supported-languages-by-resource"><code>GET /v3/languages?resource=translate_text</code></a> and look for the <code>formality</code> feature key on the target language.
272
+
Sets whether the translated text should lean towards formal or informal language. Currently supported for the following target languages:
Learn more about the <ahref="https://support.deepl.com/hc/en-us/articles/6306700061852-About-formality-plain-and-polite-tones-in-Japanese">plain/polite feature for Japanese ↗️</a>. To check formality support dynamically, call <ahref="/api-reference/languages/retrieve-supported-languages-by-resource"><code>GET /v3/languages?resource=translate_text</code></a> and look for the <code>formality</code> feature key on the target language.
271
277
272
278
<p>Setting this parameter with a target language that does not support formality will fail, unless one of the <code>prefer_...</code> options are used. Possible options are:</p>
Specify a list of instructions to customize the translation behavior. Up to 10 custom instructions can be specified, each with a maximum of 300 characters.
298
304
299
-
<Info>
300
-
The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.
Any request with the `custom_instructions` parameter enabled will default to use the `quality_optimized` model type. Requests combining `custom_instructions` and `model_type: latency_optimized` will be rejected. You can find best practices on how to write custom instructions [here](/docs/best-practices/custom-instructions).
303
311
</Info>
304
312
To check language support dynamically, call <ahref="/api-reference/languages/retrieve-supported-languages-by-resource"><code>GET /v3/languages?resource=translate_text</code></a> and check for the <code>style_rules</code> feature key on the target language.
where <resource> is one of the resources returned by `/resources` (`translate_text`, `translate_document`,
13
+
`voice`, `write`, etc.).
16
14
17
15
Each per-resource file requests `include=beta&include=external` so the vended data is the full superset. Consumers filter on the `status` and per-feature `external` fields when they want a narrower view.
18
16
19
-
## Refreshing
17
+
These files are refreshed hourly by the [`refresh-v3-languages`](../../.github/workflows/refresh-v3-languages.yml) GitHub Action, which runs [`scripts/fetch_v3_languages.py`](../../scripts/fetch_v3_languages.py) and opens a pull request whenever the API responses change. See that script's module docstring or `--help` for flags and behaviour (auth, alternate endpoints, manual local refresh).
18
+
19
+
## Stand-in files for APIs not yet in `/v3/languages`
20
+
21
+
When a DeepL API needs a supported-languages list in the docs but is not yet exposed as a `/v3/languages` resource, you can hand-write a stand-in file here and the rest of the tooling will treat it like a real response. This is how `translation_memory.json` works today, and the same pattern applies to any future API that has not landed in `/v3/languages` yet.
20
22
21
-
Set `DEEPL_AUTH_KEY` in your environment, then run:
23
+
To add one:
22
24
23
-
```sh
24
-
python3 scripts/fetch_v3_languages.py
25
-
```
25
+
1. Create `data/v3-languages/<api>.json`, where `<api>` is the resource name you expect the API to expose (snake_case, no spaces).
26
+
2. Fill it with an array shaped exactly like a real `/v3/languages?resource=<api>` response — each entry needs `lang`, `name`, `status`, `usable_as_source`, `usable_as_target`, and a `features` object (use `{}` if there are no per-language features yet).
27
+
3. Commit the file. The snippet generator picks it up on the next run (it walks `data/v3-languages/*.json` and inlines every file it finds), so `<SupportedLanguages resource="<api>" ... />` immediately works in MDX.
26
28
27
-
Flags:
29
+
You do not need to touch `scripts/fetch_v3_languages.py` or the workflow. The fetcher only writes files it actually fetched, so the manual file is left alone every run.
28
30
29
-
-`--free` — hit `https://api-free.deepl.com` instead of the Pro endpoint.
30
-
-`--base-url <url>` — point at any other host (staging, mock, local server). Also configurable via the `DEEPL_API_BASE_URL` environment variable.
31
+
Once the API does land in `/v3/languages/resources`, the very next refresh will overwrite the stand-in file with the real response and the docs stay in sync — no code change required. When that happens, double-check the fields match (the manual schema was a best guess) and delete this paragraph from the README if there are no remaining stand-ins.
31
32
32
-
The script overwrites every file in this directory.
33
+
### Current stand-ins
33
34
34
-
A scheduled GitHub Action refreshes these files automatically and opens a pull request when the responses change; manual runs are only needed for local testing.
35
+
-`translation_memory.json` — Translation Memory languages. Will be replaced automatically once Translation Memory ships as a `/v3/languages` resource.
0 commit comments