> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-update-customizations-langs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve supported languages by product
> 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 theme={null}
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 theme={null}
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 theme={null}
[
{
"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 theme={null}
curl -X GET 'https://api.deepl.com/v3/languages/products' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```json Example response (truncated) theme={null}
[
{
"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.