> ## Documentation Index
> Fetch the complete documentation index at: https://developers.deepl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve supported languages by resource
> Learn how to retrieve supported language and feature data across all DeepL API resources using the v3/languages endpoints.
Get information about all currently supported languages across all DeepL API resources.
These **BETA** endpoints replace `/v2/languages` and `/v2/glossary-language-pairs` (see the [migration guide](/api-reference/languages/migrate-from-v2-languages)). Do not use them in production; breaking changes may be pushed without advance notice (see the [changelog](/api-reference/languages/v3-languages-changelog)).
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-resource)
* [Retrieve resources](/api-reference/languages/retrieve-resources)
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).
## Resources list
To retrieve language support, decide which DeepL resource you're building for, then call `GET /v3/languages` with
the appropriate `resource` value. The `resource` parameter is required and identifies which DeepL API resource 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 resource value indicating glossaries can be created for that language, and managed via the glossary
management endpoints.
Support for glossaries within specific resources (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` object indicating which optional capabilities are available for that
language — see the [Resource features](#resource-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?resource=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```http Example request: languages for text translation theme={null}
GET /v3/languages?resource=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,
"status": "stable",
"features": {
"formality": {"status": "stable"},
"tag_handling": {"status": "stable"},
"glossary": {"status": "stable"}
}
},
{
"lang": "en",
"name": "English",
"usable_as_source": true,
"usable_as_target": false,
"status": "stable",
"features": {
"tag_handling": {"status": "stable"},
"glossary": {"status": "stable"}
}
},
{
"lang": "en-US",
"name": "English (American)",
"usable_as_source": false,
"usable_as_target": true,
"status": "stable",
"features": {
"tag_handling": {"status": "stable"},
"glossary": {"status": "stable"}
}
}
]
```
## 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.
## Resource features
Each language object includes a `features` object indicating which optional capabilities are supported for that language
with the requested resource. Each key is a feature name; the value is an object with at least a `status` field.
To check whether a feature is supported, check that the key exists in the `features` object:
```text theme={null}
// Feature supported:
"features": { "formality": { "status": "stable" } }
// Feature not supported:
"features": {}
```
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
a key in the target language's `features` object.
* **Source-and-target**: `tag_handling` and `glossary` must be supported by both languages. Check that the
feature key is present in *both* the source and target language's `features` objects.
* **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 key to check, and whether to check the source language, target language, or both.
### Resource feature reference
The table below lists all feature keys that can appear in a language's `features` object.
| **Feature** | **Check language support on** | **Resources** | **Description** |
| ---------------------------- | ----------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_detection` | source | `translate_text`, `translate_document`, `voice`, `write` | Language can be automatically detected as the source language. |
| `style_rules` | target | `translate_text` | Language supports style rules that guide how DeepL translates text. Used with the `custom_instructions` and `style_id` parameters on the translate endpoint. |
| `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 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 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). |
## Filtering by availability
By default, `GET /v3/languages` returns only stable languages and features. Use the `include` query parameter
to request additional languages and features based on their availability status:
| **Value** | **Effect** |
| ---------- | -------------------------------------------------------------- |
| `beta` | Includes languages and features in beta, in addition to stable |
| `external` | Includes features that rely on third-party service providers |
Values can be combined with repeated parameters: `?include=beta&include=external`.
The `status` field on each language object and each feature object indicates its availability:
| **Status** | **Meaning** |
| -------------- | --------------------------------- |
| `stable` | Generally available |
| `beta` | Available for testing; may change |
| `early_access` | Limited availability; may change |
## Retrieving resources programmatically
Use the `/v3/languages/resources` endpoint to retrieve the list of resources 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` objects.
```sh theme={null}
curl -X GET 'https://api.deepl.com/v3/languages/resources' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
```
```json Example response (truncated) theme={null}
[
{
"name": "translate_text",
"features": [
{
"name": "formality",
"needs_target_support": true
},
{
"name": "style_rules",
"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 feature keys may be added to the `features` object
* 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 feature keys in the `features` object. 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` object 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 new keys in the `features` object 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.