docs: add v3/languages cross-references to endpoint docs

Daniel Jones · claude · Daniel Jones · commit 981d79fcf46e · 2026-05-03T12:56:25.000+02:00
Adds a sentence to each language-conditional parameter pointing to
GET /v3/languages?resource=&lt;resource&gt; for dynamic feature support checks,
replacing hardcoded language lists where applicable.

Endpoints updated:
- translate: source_lang (auto_detection), formality, glossary_id,
  custom_instructions (style_rules feature), tag_handling
- document: formality, glossary_id
- improve-text: target_lang, writing_style, tone
- voice: supported languages section
- multilingual-glossaries: language support mention

Also adds auto_detection to language-detection best-practices guide and
updates supported-languages page to reference v3/languages endpoint.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/api-reference/document.mdx b/api-reference/document.mdx
@@ -146,7 +146,7 @@ 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. Possible options are:
+  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-product"><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>
@@ -156,7 +156,7 @@ These examples are for demonstration purposes only. In production code, the auth
   </ul>
 </ParamField>
 <ParamField body="glossary_id" type="string">
-  A unique ID assigned to a glossary.  
+  A unique ID assigned to a glossary. To check glossary support for a language pair, call <a href="/api-reference/languages/retrieve-supported-languages-by-product"><code>GET /v3/languages?resource=translate_document</code></a> and verify the <code>glossary</code> feature key is present on both the source and target language.
 </ParamField>
 <ParamField body="output_format" type="string">
   File extension of desired format of translated file, for example: `pdf`. If unspecified, by default the translated file will be in the same format as the input file.
diff --git a/api-reference/improve-text.mdx b/api-reference/improve-text.mdx
@@ -62,7 +62,7 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
   Text to be improved. Only UTF-8-encoded plain text is supported. Improvements are returned in the same order as they are requested. Each of the parameter values may contain multiple sentences.
 </ParamField>
 <ParamField body="target_lang" type="string">
-  The language of the improved text. A list of supported languages have not yet been added to the `/languages` endpoint. Currently, the following languages are supported:
+  The language of the improved text. You can also retrieve supported languages programmatically via <a href="/api-reference/languages/retrieve-supported-languages-by-product"><code>GET /v3/languages?resource=write</code></a>. Currently, the following languages are supported:
 
   * `de` (German)
   * `en-GB` (British English)
@@ -110,7 +110,7 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
 
   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.
 
-  It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included.
+  It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included. To check writing style support dynamically, call <a href="/api-reference/languages/retrieve-supported-languages-by-product"><code>GET /v3/languages?resource=write</code></a> and look for the <code>writing_style</code> feature key on the target language.
 </ParamField>
 <ParamField body="tone" type="enum">
   Changes the tone of your improvements.
@@ -142,7 +142,7 @@ curl -X POST 'https://api.deepl.com/v2/write/rephrase' \
 
   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.
 
-  It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included.
+  It’s not possible to include both `writing_style` and `tone` in a request; only one or the other can be included. To check tone support dynamically, call <a href="/api-reference/languages/retrieve-supported-languages-by-product"><code>GET /v3/languages?resource=write</code></a> and look for the <code>tone</code> feature key on the target language.
 </ParamField>
 
 ### Response body descriptions
diff --git a/api-reference/multilingual-glossaries.mdx b/api-reference/multilingual-glossaries.mdx
@@ -16,7 +16,7 @@ description: "Manage and use DeepL glossaries"
 
 ## Overview
 
-The `glossaries` endpoints let you work with [DeepL glossaries](https://support.deepl.com/hc/en-us/articles/360021634540-About-the-glossary), which let you specify specific translations for words or short phrases. Each glossary contains a mapping of source phrases to target phrases. During translation, DeepL intelligently flexes entries to account for case, gender, tense, and other grammar features (if the target language has flexion). You can create glossaries with [any of the languages listed here](/docs/getting-started/supported-languages).
+The `glossaries` endpoints let you work with [DeepL glossaries](https://support.deepl.com/hc/en-us/articles/360021634540-About-the-glossary), which let you specify specific translations for words or short phrases. Each glossary contains a mapping of source phrases to target phrases. During translation, DeepL intelligently flexes entries to account for case, gender, tense, and other grammar features (if the target language has flexion). You can create glossaries with [any of the languages listed here](/docs/getting-started/supported-languages). To retrieve supported glossary languages programmatically, call [`GET /v3/languages?resource=glossary`](/api-reference/languages/retrieve-supported-languages-by-product).
 
 A **glossary** contains (several) **dictionaries**. A **dictionary** is a mapping of source phrases to target phrases for a single language pair, like this:
 
diff --git a/api-reference/translate.mdx b/api-reference/translate.mdx
@@ -184,7 +184,7 @@ Note that we do not include examples for our client libraries in every single se
   </Warning>
 </ParamField>
 <ParamField body="source_lang" type="string">
-  Language of the text to be translated. If omitted, the API will attempt to detect the language of the text and translate it. You can find supported source languages <a href="/docs/getting-started/supported-languages">here</a>.
+  Language of the text to be translated. If omitted, the API will attempt to detect the language of the text and translate it. You can find supported source languages <a href="/docs/getting-started/supported-languages">here</a>. To check which languages support automatic source language detection, call <a href="/api-reference/languages/retrieve-supported-languages-by-product"><code>GET /v3/languages?resource=translate_text</code></a> and look for the <code>auto_detection</code> feature key in the language's <code>features</code> object.
 </ParamField>
 <ParamField body="target_lang" type="string" required>
   The language into which the text should be translated. You can find supported target languages <a href="/docs/getting-started/supported-languages">here</a>.
@@ -267,7 +267,7 @@ 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>.
+  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-product"><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>
@@ -283,6 +283,7 @@ error.
   <Note>
     <strong>Important:</strong> This requires the <code>source_lang</code> parameter to be set and the language pair of the glossary has to match the language pair of the request.
   </Note>
+  To check glossary support for a language pair, call <a href="/api-reference/languages/retrieve-supported-languages-by-product"><code>GET /v3/languages?resource=translate_text</code></a> and verify the <code>glossary</code> feature key is present on both the source and target language.
 </ParamField>
 <ParamField body="style_id" type="string">
   Specify the style rule list to use for the translation which can be used to customize translations according to the selected formatting and style conventions.
@@ -300,6 +301,7 @@ error.
 
     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-product"><code>GET /v3/languages?resource=translate_text</code></a> and look for the <code>style_rules</code> feature key on the target language.
 </ParamField>
 <ParamField body="translation_memory_id" type="string">
   The [translation memory](/api-reference/translation-memory/list-translation-memories) to use for the translation. The value should be the UUID of a translation memory associated with your account.
@@ -326,6 +328,7 @@ error.
     <li><code>xml</code>: Enable XML tag handling; see <a href="/docs/xml-and-html-handling/xml">XML handling</a>.</li>
     <li><code>html</code>: Enable HTML tag handling; see <a href="/docs/xml-and-html-handling/html">HTML handling</a>.</li>
   </ul>
+  To check tag handling support for a language pair, call <a href="/api-reference/languages/retrieve-supported-languages-by-product"><code>GET /v3/languages?resource=translate_text</code></a> and verify the <code>tag_handling</code> feature key is present on both the source and target language.
 </ParamField>
 <ParamField body="tag_handling_version" type="string">
   Select which version of the tag handling algorithm should be used. See <a href="/docs/xml-and-html-handling/tag-handling-v2">tag handling v2</a>.
diff --git a/api-reference/voice.mdx b/api-reference/voice.mdx
@@ -44,7 +44,7 @@ To start using the Voice API:
 
 We support a wide range of source and target languages (see  below). However, while translation is always provided by
 DeepL, for some languages we use external service partners to provide transcription and translated speech.
-All source languages can be translated into any target language.
+All source languages can be translated into any target language. To retrieve supported languages and feature availability programmatically, call [`GET /v3/languages?resource=voice`](/api-reference/languages/retrieve-supported-languages-by-product) and check for the `transcription`, `transcription_external`, `translated_speech`, and `translated_speech_external` feature keys.
 
 <Accordion title="Show supported languages">
 | **Language** | **Transcription** | **Translation** | <Badge color="green">closed beta</Badge><br/>Translated Speech |
diff --git a/docs/best-practices/language-detection.mdx b/docs/best-practices/language-detection.mdx
@@ -7,3 +7,5 @@ public: true
 Our translation and document translation endpoints allow you to automatically detect the source language or set it. It is recommended to set the source language whenever possible, as this has a positive effect on translation quality. If you cannot specify the source language, the more context you provide, the better your results will be. Single words can lead to incorrect language detection, so the longer your text, the more reliable it will be.
 
 If you are translating single words or very short sentences, the results will generally be more reliable if the source language is specified. You can find all available [source languages here](/api-reference/languages), and you can read more about translation context in the next chapter.
+
+Not all source languages support automatic detection. To check which languages can be auto-detected, call [`GET /v3/languages?resource=translate_text`](/api-reference/languages/retrieve-supported-languages-by-product) and look for the `auto_detection` feature key on each language.
diff --git a/docs/getting-started/supported-languages.mdx b/docs/getting-started/supported-languages.mdx
@@ -6,7 +6,7 @@ sidebarTitle: "Languages supported"
 mode: "wide"
 ---
 
-The DeepL API supports the following languages. These can also be retrieved programmatically via the [`/languages` endpoint](/api-reference/languages/retrieve-supported-languages).
+The DeepL API supports the following languages. These can also be retrieved programmatically via the [`/v3/languages` endpoint](/api-reference/languages/retrieve-supported-languages-by-product), which returns language support per resource along with feature availability (e.g. formality, glossary, auto-detection). The legacy [`/v2/languages` endpoint](/api-reference/languages/retrieve-supported-languages) is also available but deprecated.
 
 ## API Supported Languages
 
