DeepLcom · daniel-jones-dev · May 22, 2026
diff --git a/.github/workflows/refresh-v3-languages.yml b/.github/workflows/refresh-v3-languages.yml
@@ -23,7 +23,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v5
 
-      - name: Fetch latest /v3/languages responses
+      - name: Fetch latest /v3/languages responses and refresh snippet
         env:
           DEEPL_AUTH_KEY: ${{ secrets.DEEPL_API_KEY }}
         run: python3 scripts/fetch_v3_languages.py
@@ -37,14 +37,17 @@ jobs:
           title: "chore(v3-languages): refresh vended responses"
           body: |
             Automated refresh of `data/v3-languages/` from `https://api.deepl.com/v3/languages`,
-            opened by the `refresh-v3-languages` workflow.
+            with `snippets/supported-languages.jsx` regenerated from the new responses. Opened by
+            the `refresh-v3-languages` workflow.
 
             This PR is rewritten in place on each run: if the vended responses change again
             before merge, the branch is force-pushed with a new single squashed commit so the
             diff against `main` always reflects the latest API state. If a run finds the
             responses identical to what is already on the branch, the branch is left untouched.
             If a run finds the responses match `main` (e.g. the PR was merged), this PR is
             closed and the branch deleted automatically.
-          add-paths: data/v3-languages/**
+          add-paths: |
+            data/v3-languages/**
+            snippets/supported-languages.jsx
           delete-branch: true
           labels: automated, v3-languages
diff --git a/api-reference/document.mdx b/api-reference/document.mdx
@@ -4,6 +4,8 @@ sidebarTitle: "Overview"
 public: true
 ---
 
+import { SupportedLanguages } from "/snippets/supported-languages.jsx"
+
 The document translation API allows you to translate whole documents and supports the following file types and extensions:
 
 * `docx` / `doc` - Microsoft Word Document
@@ -146,7 +148,11 @@ These examples are for demonstration purposes only. In production code, the auth
   The name of the uploaded file. Can be used as an alternative to including the file name in the file part's content disposition.
 </ParamField>
 <ParamField body="formality" type="string">
-  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 <a href="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 <a href="/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:
+  Sets whether the translated text should lean towards formal or informal language. Currently supported for the following target languages:
+
+  <SupportedLanguages mode="bullets" resource="translate_document" feature="formality" direction="target" />
+
+  Learn more about the plain/polite feature for Japanese <a href="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 <a href="/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:
   <ul>
     <li>`default` (default)</li>
     <li>`more` - for a more formal language</li>

diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx
@@ -3,6 +3,9 @@ title: "Improve text"
 public: true
 sidebarTitle: "Overview"
 ---
+
+import { SupportedLanguages } from "/snippets/supported-languages.jsx"
+
 <Info>
   **Introducing DeepL API for Write**
 
@@ -64,17 +67,7 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
 <ParamField body="target_lang" type="string">
   The language of the improved text. Currently, the following languages are supported:
 
-  * `de` (German)
-  * `en-GB` (British English)
-  * `en-US` (American English)
-  * `es` (Spanish)
-  * `fr` (French)
-  * `it` (Italian)
-  * `ja` (Japanese)
-  * `ko` (Korean)
-  * `pt-BR` (Brazilian Portuguese)
-  * `pt-PT` (Portuguese)
-  * `zh`/`zh-Hans` (simplified Chinese)
+  <SupportedLanguages mode="bullets" resource="write" direction="target" />
 
   You can also retrieve supported languages programmatically via <a href="/api-reference/languages/retrieve-supported-languages-by-resource"><code>GET /v3/languages?resource=write</code></a>.
 

diff --git a/api-reference/style-rules.mdx b/api-reference/style-rules.mdx
@@ -4,6 +4,8 @@ sidebarTitle: "Overview"
 description: "Manage a shared list of rules for style, formatting, and more"
 ---
 
+import { SupportedLanguages } from "/snippets/supported-languages.jsx"
+
 <Info>
     The Style Rules API is currently available only to Pro API subscribers.
 </Info>
@@ -161,7 +163,9 @@ Create a new style rule list with configured rules and optional custom instructi
   The name of the style rule list. Maximum length: 1024 characters.
 </ParamField>
 <ParamField body="language" type="string" required>
-  The target language for the style rules. Supported values: `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh`.
+  The target language for the style rules. Supported values:
+
+  <SupportedLanguages resource="style_rules" />
 </ParamField>
 <ParamField body="configured_rules" type="object">
   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.

diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx
@@ -5,6 +5,8 @@ description: "API reference for translating text with the DeepL API."
 public: true
 ---
 
+import { SupportedLanguages } from "/snippets/supported-languages.jsx"
+
 The text-translation API currently consists of a single endpoint, `translate`, which is described below.
 
 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.
   </Info>
 </ParamField>
 <ParamField body="formality" type="string">
-  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 <a href="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 <a href="/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.
+  Sets whether the translated text should lean towards formal or informal language. Currently supported for the following target languages:
+
+  <SupportedLanguages mode="bullets" resource="translate_text" feature="formality" direction="target" />
+
+  Learn more about the <a href="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 <a href="/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.
 
   <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>
   <ul>
@@ -296,9 +302,11 @@ error.
 <ParamField body="custom_instructions" type="array[string]">
   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.
 
-  <Info>
-    The target language must be `de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `zh` or any variants of these languages.
+  The target language must be one of:
+
+  <SupportedLanguages resource="translate_text" feature="style_rules" direction="target" />
 
+  <Info>
     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).
   </Info>
   To check language support dynamically, call <a href="/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.

diff --git a/data/v3-languages/README.md b/data/v3-languages/README.md
@@ -7,28 +7,29 @@ This directory holds verbatim JSON responses from the DeepL `/v3/languages` endp
 | File | Endpoint |
 |---|---|
 | `resources.json` | `GET /v3/languages/resources` |
-| `translate_text.json` | `GET /v3/languages?resource=translate_text&include=beta&include=external` |
-| `translate_document.json` | `GET /v3/languages?resource=translate_document&include=beta&include=external` |
-| `voice.json` | `GET /v3/languages?resource=voice&include=beta&include=external` |
-| `write.json` | `GET /v3/languages?resource=write&include=beta&include=external` |
-| `glossary.json` | `GET /v3/languages?resource=glossary&include=beta&include=external` |
-| `style_rules.json` | `GET /v3/languages?resource=style_rules&include=beta&include=external` |
+| `<resource>.json` | `GET /v3/languages?resource=<resource>&include=beta&include=external` |
+
+where <resource> is one of the resources returned by `/resources` (`translate_text`, `translate_document`,
+`voice`, `write`, etc.).
 
 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.
 
-## Refreshing
+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).
+
+## Stand-in files for APIs not yet in `/v3/languages`
+
+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.
 
-Set `DEEPL_AUTH_KEY` in your environment, then run:
+To add one:
 
-```sh
-python3 scripts/fetch_v3_languages.py
-```
+1. Create `data/v3-languages/<api>.json`, where `<api>` is the resource name you expect the API to expose (snake_case, no spaces).
+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).
+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.
 
-Flags:
+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.
 
-- `--free` — hit `https://api-free.deepl.com` instead of the Pro endpoint.
-- `--base-url <url>` — point at any other host (staging, mock, local server). Also configurable via the `DEEPL_API_BASE_URL` environment variable.
+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.
 
-The script overwrites every file in this directory.
+### Current stand-ins
 
-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.
+- `translation_memory.json` — Translation Memory languages. Will be replaced automatically once Translation Memory ships as a `/v3/languages` resource.
diff --git a/data/v3-languages/resources.json b/data/v3-languages/resources.json
@@ -68,6 +68,10 @@
         "needs_source_support": true,
         "needs_target_support": true
       },
+      {
+        "name": "spoken_terms",
+        "needs_source_support": true
+      },
       {
         "name": "transcription",
         "needs_source_support": true