Merge pull request #332 from DeepLcom/v3-langs/ga-v3-languages-updates

docs(v3-languages): document latest API changes

Author: Daniel Jones

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

@@ -5,20 +5,20 @@ description: "Pseudocode examples for common language and feature lookup pattern
 ---
 
 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.
+as pseudocode and are resource-agnostic unless otherwise noted.
 
 For background on how features and feature dependency types work, see the
-[overview](/api-reference/languages/retrieve-supported-languages-by-product).
+[overview](/api-reference/languages/retrieve-supported-languages-by-resource).
 
 ---
 
 ## 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
+A single call to `GET /v3/languages` returns all languages for a resource. Filter by `usable_as_source` and
 `usable_as_target` to populate each dropdown separately.
 
 ```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
 
 languages = response
 
@@ -34,15 +34,15 @@ render target_dropdown(target_options)
 ## Show formality options only when supported
 
 `formality` only needs to be supported by the target language. Check the selected target language's `features`
-array — no need to look at the source language.
+object — no need to look at the source language.
 
 ```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
 
 languages = response
 target = languages.find(l => l.lang == selected_target_lang)
 
-if target.features.includes("formality"):
+if "formality" in target.features:
     show formality_selector  // e.g. ["default", "more", "less"]
 else:
     hide formality_selector
@@ -55,15 +55,15 @@ else:
 `glossary` must be supported by both languages.
 
 ```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=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")
+glossary_allowed = "glossary" in source.features
+               and "glossary" in target.features
 ```
 
 ---
@@ -73,34 +73,34 @@ glossary_allowed = source.features.includes("glossary")
 Filter to targets where both the source and target support the `glossary` feature.
 
 ```
-GET /v3/languages?product=translate_text
+GET /v3/languages?resource=translate_text
 
 languages = response
 source_lang = "en"
 
 source = languages.find(l => l.lang == source_lang)
 
-if not source.features.includes("glossary"):
+if "glossary" not in source.features:
     return []  // source doesn't support glossary at all
 
 targets_with_glossary = languages
     .filter(l => l.usable_as_target)
-    .filter(l => l.features.includes("glossary"))
+    .filter(l => "glossary" in l.features)
 ```
 
 ---
 
-## Show writing style options for the Write product
+## Show writing style options for the Write resource
 
-`writing_style` is a target-only feature on the `write` product. Check the target language's `features` array.
+`writing_style` is a target-only feature on the `write` resource. Check the target language's `features` object.
 
 ```
-GET /v3/languages?product=write
+GET /v3/languages?resource=write
 
 languages = response
 target = languages.find(l => l.lang == selected_target_lang)
 
-if target.features.includes("writing_style"):
+if "writing_style" in target.features:
     show writing_style_selector
 else:
     hide writing_style_selector
@@ -110,12 +110,12 @@ else:
 
 ## Check if style rules are available for a target language
 
-Use `product=style_rules` to query which languages support style rules. Style rules are target-language only — check
-that the target language is listed in the response. The `style_rules` product has no additional features, so only
+Use `resource=style_rules` to query which languages support style rules. Style rules are target-language only — check
+that the target language is listed in the response. The `style_rules` resource has no additional features, so only
 the language availability needs to be checked.
 
 ```
-GET /v3/languages?product=style_rules
+GET /v3/languages?resource=style_rules
 
 languages = response
 target = languages.find(l => l.lang == selected_target_lang)
@@ -130,25 +130,24 @@ else:
 
 ## Determine feature support programmatically
 
-Use `/v3/languages/products` to drive feature checks at runtime — without hardcoding which features need
+Use `/v3/languages/resources` to drive feature checks at runtime — without hardcoding which features need
 target-only or both-language support into your client.
 
 ```
-GET /v3/languages/products
-GET /v3/languages?product=translate_text
+GET /v3/languages/resources
+GET /v3/languages?resource=translate_text
 
-products = first response
+resources = first response
 languages = second response
 
-product = products.find(p => p.name == "translate_text")
+resource = resources.find(r => r.name == "translate_text")
 source = languages.find(l => l.lang == source_lang)
 target = languages.find(l => l.lang == target_lang)
 
-for feature in product.features:
+for feature in resource.features:
     supported = true
-    if feature.needs_source_support and not source.features.includes(feature.name):
+    if feature.needs_source_support and feature.name not in source.features:
         supported = false
-    if feature.needs_target_support and not target.features.includes(feature.name):
+    if feature.needs_target_support and feature.name not in target.features:
         supported = false
 ```
-

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

@@ -20,18 +20,18 @@ 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
+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?product=translate_text
+GET /v3/languages?resource=translate_text
 ```
 
-### New product identifiers
+### New resource 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 languages are implicitly tied to text and document translation. v3 introduces an explicit `resource` parameter that applies across all DeepL API resources:
 
-| v2 | v3 `product` value |
+| **v2** | **v3 `resource` value** |
 |---|---|
 | *(implicit, text/document translation only)* | `translate_text` |
 | *(implicit, text/document translation only)* | `translate_document` |
@@ -43,16 +43,16 @@ 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 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 |
+| **v2 field** | **v3 equivalent** |
 |---|---|
-| `"supports_formality": true` | `"features": ["formality"]` on the language object |
+| `"supports_formality": true` | `"formality"` key present in the language's `features` object |
 
 For example, querying languages for text translation:
 
 ```sh
-curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
+curl -X GET 'https://api.deepl.com/v3/languages?resource=translate_text' \
 --header 'Authorization: DeepL-Auth-Key [yourAuthKey]'
 ```
 
@@ -63,29 +63,39 @@ curl -X GET 'https://api.deepl.com/v3/languages?product=translate_text' \
     "name": "German",
     "usable_as_source": true,
     "usable_as_target": true,
-    "features": ["formality", "tag_handling", "glossary"]
+    "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,
-    "features": ["tag_handling", "glossary"]
+    "status": "stable",
+    "features": {
+      "tag_handling": {"status": "stable"},
+      "glossary": {"status": "stable"}
+    }
   }
 ]
 ```
 
-The response indicates German supports `formality`, but English (American) does not.
+The response indicates German supports `formality` (key present in `features`), but English (American) does not (key absent).
 
-See the [overview](/api-reference/languages/retrieve-supported-languages-by-product) for the full list of features per product.
+See the [overview](/api-reference/languages/retrieve-supported-languages-by-resource) for the full list of features per resource.
 
 ### Response field names
 
-| v2 field             | v3 field               |
-|----------------------|------------------------|
-| `language`           | `lang`                 |
-| `name`               | `name` *(unchanged)*   |
-| `supports_formality` | `features["formality]` |
+| **v2 field**             | **v3 field**                                          |
+|----------------------|---------------------------------------------------|
+| `language`           | `lang`                                            |
+| `name`               | `name` *(unchanged)*                              |
+| `supports_formality` | `"formality"` key in `features` object            |
+| *(not present)*      | `status`                                          |
 
 ### Language code casing
 
@@ -97,6 +107,6 @@ DeepL accepts language codes case-insensitively as input across all endpoints. H
 
 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.
+- `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.

…guages/retrieve-languages-by-product.mdx …uages/retrieve-languages-by-resource.mdxapi-reference/languages/retrieve-languages-by-product.mdx renamed to api-reference/languages/retrieve-languages-by-resource.mdx api-reference/languages/retrieve-languages-by-product.mdx renamed to api-reference/languages/retrieve-languages-by-resource.mdx

@@ -1,9 +1,11 @@
 ---
-openapi: get /v3/languages/products
-title: "Retrieve language products"
+openapi: get /v3/languages/resources
+title: "Retrieve language resources"
 tag: "BETA"
+description: "Learn how to retrieve the list of DeepL API resources and their supported language features."
 ---
 
 <Info>
 This endpoint is available for testing in BETA. Breaking changes may be pushed with little or no advance notice, and we provide no guarantees of stability.
 </Info>
+