Migrating from v2/languages

How to migrate from the v2/languages endpoint to the v3/languages endpoints.

This page covers the differences between the /v2/languages endpoint and the v3 endpoints, and how to update your integration.

Only GET requests are supported on the v3 endpoints. Unlike /v2/languages, POST is not supported.

What changed

Single endpoint for source and target

v2 uses a single endpoint with a type query parameter to distinguish source from target:

GET /v2/languages?type=source
GET /v2/languages?type=target

v3 uses a single endpoint that returns all languages for a resource, with each language indicating whether it is usable as a source, a target, or both:

GET /v3/languages?resource=translate_text

New resource identifiers

v2 languages are implicitly tied to text and document translation. v3 introduces an explicit resource parameter that applies across all DeepL API resources:

v2	v3 resource value
(implicit, text/document translation only)	translate_text
(implicit, text/document translation only)	translate_document
(separate /v2/glossary-language-pairs endpoint)	glossary
(not supported)	voice
(not supported)	write

The v3 endpoints replace both /v2/languages and /v2/glossary-language-pairs.

Features instead of supports_formality

v2 target languages include a boolean supports_formality field. v3 replaces this with a features object that covers additional capabilities per resource:

v2 field	v3 equivalent
"supports_formality": true	"formality" key present in the language’s features object

For example, querying languages for text translation:

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

Example response (truncated)

[
  {
    "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-US",
    "name": "English (American)",
    "usable_as_source": false,
    "usable_as_target": true,
    "status": "stable",
    "features": {
      "tag_handling": {"status": "stable"},
      "glossary": {"status": "stable"}
    }
  }
]

The response indicates German supports formality (key present in features), but English (American) does not (key absent).

See the overview for the full list of features per resource.

Response field names

v2 field	v3 field
language	lang
name	name (unchanged)
supports_formality	"formality" key in features object
(not present)	status

Language code casing

v2 returned language codes in non-standard casing (e.g. EN-US, ZH-HANT). v3 returns codes compliant with BCP 47: lowercase base language (en, de), uppercase region subtag (en-US, pt-BR), and title-case script subtag (zh-Hant).

DeepL accepts language codes case-insensitively as input across all endpoints. However, if your integration stores or compares codes returned by /v2/languages, update those comparisons to be case-insensitive or to expect the new casing.

Migrating glossary language pair queries

If you currently use /v2/glossary-language-pairs to discover which language pairs are supported for glossaries, use one of the following:

• GET /v3/languages?resource=glossary to check which languages support glossary management (i.e. creating a glossary for that language). Filter by usable_as_source and usable_as_target as needed. Any combination of a valid source and target language is a supported glossary language pair.
• GET /v3/languages?resource=translate_text to check which languages support using a glossary during text translation. Languages with a "glossary" key in their features object support the glossary_id parameter on the translate endpoint.
• Similarly, use resource=translate_document to check glossary support for document translation.