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). Do not use them in production; breaking changes may be pushed without advance notice (see the changelog).

We also provide auto-generated API specs from DeepL’s OpenAPI file, for use with API clients and code generation tools:

• Retrieve 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.

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 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.

cURL

Example request: languages for text translation

curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'

HTTP Request

Example request: languages for text translation

GET /v3/languages?resource=translate_text HTTP/2
Host: api.deepl.com
Authorization: DeepL-Auth-Key [yourAuthKey]
User-Agent: YourApp/1.2.3

Example response

[
  {
    "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. 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 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:

// 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.

curl -X GET 'https://api.deepl.com/v3/languages/resources' \
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'

Example response (truncated)

[
  {
    "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 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.