v3/languages beta

api-reference/api-reference/retrieve-languages/language-feature-use-cases-beta.mdx

@@ -0,0 +1,170 @@
+---
+title: 'Common use cases [BETA]'
+description: "Pseudocode examples for common language and feature lookup patterns using the v3/languages endpoints."
+---
+
+This page shows how to use the `/v3/languages` endpoints for common integration tasks. Examples are written
+as pseudocode and are product-agnostic unless otherwise noted.
+
+For background on how features and feature dependency types work, see the
+[overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta).
+
+<Note>
+    The examples below do not account for language pair exceptions. For most integrations this is fine — exceptions
+    are rare and the API handles them gracefully by disabling the unsupported feature rather than failing. If you
+    need precise feature support for specific language pairs, see
+    [Handling language pair exceptions](#handling-language-pair-exceptions) at the end of this page.
+</Note>
+
+---
+
+## Populate source and target language dropdowns
+
+A single call to `GET /v3/languages` returns all languages for a product. Filter by `usable_as_source` and
+`usable_as_target` to populate each dropdown separately.
+
+```
+GET /v3/languages?product=translate_text
+
+languages = response
+
+source_options = languages.filter(l => l.usable_as_source)
+target_options = languages.filter(l => l.usable_as_target)
+
+render source_dropdown(source_options)
+render target_dropdown(target_options)
+```
+
+---
+
+## Show formality options only when supported
+
+`formality` is a target-only feature. Check the selected target language's `features` array — no need to look
+at the source language.
+
+```
+GET /v3/languages?product=translate_text
+
+languages = response
+target = languages.find(l => l.lang == selected_target_lang)
+
+if target.features.includes("formality"):
+    show formality_selector  // e.g. ["default", "more", "less"]
+else:
+    hide formality_selector
+```
+
+---
+
+## Check if a glossary can be used for a given language pair
+
+`glossary` is a source-and-target feature — both languages must support it.
+
+```
+GET /v3/languages?product=translate_text
+
+languages = response
+
+source = languages.find(l => l.lang == source_lang)
+target = languages.find(l => l.lang == target_lang)
+
+glossary_allowed = source.features.includes("glossary")
+               and target.features.includes("glossary")
+```
+
+---
+
+## List target languages that accept glossaries from a given source language
+
+Filter to targets where both the source and target support the `glossary` feature.
+
+```
+GET /v3/languages?product=translate_text
+
+languages = response
+source_lang = "en"
+
+source = languages.find(l => l.lang == source_lang)
+
+if not source.features.includes("glossary"):
+    return []  // source doesn't support glossary at all
+
+targets_with_glossary = languages
+    .filter(l => l.usable_as_target)
+    .filter(l => l.features.includes("glossary"))
+```
+
+---
+
+## Show writing style options for the Write product
+
+`writing_style` is a target-only feature on the `write` product. Check the target language's `features` array.
+
+```
+GET /v3/languages?product=write
+
+languages = response
+target = languages.find(l => l.lang == selected_target_lang)
+
+if target.features.includes("writing_style"):
+    show writing_style_selector
+else:
+    hide writing_style_selector
+```
+
+---
+
+## Determine feature support programmatically
+
+Use `/v3/languages/products` to drive feature checks at runtime — without hardcoding which features are
+target-only or source-and-target into your client.
+
+```
+GET /v3/languages/products
+GET /v3/languages?product=translate_text
+
+products = first response
+languages = second response
+
+product = products.find(p => p.name == "translate_text")
+source = languages.find(l => l.lang == source_lang)
+target = languages.find(l => l.lang == target_lang)
+
+for feature in product.features:
+    supported = true
+    if feature.required_on_source and not source.features.includes(feature.name):
+        supported = false
+    if feature.required_on_target and not target.features.includes(feature.name):
+        supported = false
+```
+
+---
+
+## Handling language pair exceptions
+
+In rare cases, feature support for a specific pair differs from what the individual language objects indicate.
+The `/v3/languages/exceptions` endpoint exposes these cases. When an exception exists for a pair, its `features`
+array is authoritative — use it directly instead of intersecting the individual language `features` arrays.
+
+The example below shows a full glossary pair check that accounts for exceptions:
+
+```
+GET /v3/languages?product=translate_text
+GET /v3/languages/exceptions?product=translate_text
+
+languages = first response
+exceptions = second response
+
+exception = exceptions.find(e => e.source_lang == source_lang && e.target_lang == target_lang)
+
+if exception:
+    features = exception.features
+else:
+    source = languages.find(l => l.lang == source_lang)
+    target = languages.find(l => l.lang == target_lang)
+    features = intersect(source.features, target.features)
+
+glossary_allowed = features.includes("glossary")
+```
+
+The same pattern applies to any feature check — replace `"glossary"` with the feature you are checking.

api-reference/api-reference/retrieve-languages/migrate-from-v2-languages.mdx

@@ -0,0 +1,102 @@
+---
+title: 'Migrating from v2/languages'
+description: "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.
+
+<Warning>
+  Only `GET` requests are supported on the v3 endpoints. Unlike `/v2/languages`, POST is not supported.
+</Warning>
+
+## 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 product, with each language indicating whether it is
+usable as a source, a target, or both:
+
+```
+GET /v3/languages?product=translate_text
+```
+
+### New product identifiers
+
+v2 languages are implicitly tied to text and document translation. v3 introduces an explicit `product` parameter that applies across all DeepL API products:
+
+| v2 | v3 `product` 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` array that covers additional capabilities per product:
+
+| v2 field | v3 equivalent |
+|---|---|
+| `"supports_formality": true` | `"features": ["formality"]` on the language object |
+
+For example, querying languages for text translation:
+
+```sh
+curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
+```
+
+```json Example response (truncated)
+[
+  {
+    "lang": "de",
+    "name": "German",
+    "usable_as_source": true,
+    "usable_as_target": true,
+    "features": ["formality", "tag_handling", "glossary"]
+  },
+  {
+    "lang": "en-US",
+    "name": "English (American)",
+    "usable_as_source": false,
+    "usable_as_target": true,
+    "features": ["tag_handling", "glossary"]
+  }
+]
+```
+
+The response indicates German supports `formality`, but English (American) does not.
+
+See the [overview](/api-reference/api-reference/retrieve-languages/retrieve-supported-languages-by-product-beta) for the full list of features per product.
+
+### Response field names
+
+| v2 field             | v3 field               |
+|----------------------|------------------------|
+| `language`           | `lang`                 |
+| `name`               | `name` *(unchanged)*   |
+| `supports_formality` | `features["formality]` |
+
+### 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?product=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?product=translate_text` to check which languages support using a glossary during text translation. Languages that include `"glossary"` in their `features` array support the `glossary_id` parameter on the translate endpoint.
+- Similarly, use `product=translate_document` to check glossary support for document translation.

api-reference/api-reference/retrieve-languages/retrieve-language-pair-exceptions-beta.mdx

@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages/exceptions
+title: "Retrieve language pair exceptions [BETA]"
+---

api-reference/api-reference/retrieve-languages/retrieve-languages-beta.mdx

@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages
+title: "Retrieve languages [BETA]"
+---

api-reference/api-reference/retrieve-languages/retrieve-products-beta.mdx

@@ -0,0 +1,4 @@
+---
+openapi: get /v3/languages/products
+title: "Retrieve language products [BETA]"
+---