Merge pull request #271 from DeepLcom/v3-languages-required-wording

v3/languages: improve wording around features "required"

Author: daniel-jones-dev

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

@@ -39,8 +39,8 @@ 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.
+`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.
 
 ```
 GET /v3/languages?product=translate_text
@@ -58,7 +58,7 @@ else:
 
 ## Check if a glossary can be used for a given language pair
 
-`glossary` is a source-and-target feature — both languages must support it.
+`glossary` must be supported by both languages.
 
 ```
 GET /v3/languages?product=translate_text
@@ -116,8 +116,8 @@ else:
 
 ## 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.
+Use `/v3/languages/products` to drive feature checks at runtime — without hardcoding which features need
+target-only or both-language support into your client.
 
 ```
 GET /v3/languages/products

api-reference/languages/retrieve-supported-languages-by-product.mdx

@@ -117,24 +117,24 @@ User-Agent: YourApp/1.2.3
 Each language object includes a `features` array indicating which optional capabilities are supported for that language
 with the requested product.
 
-A feature may be required on the source language, the target language, or both. For example, for text translation:
+To use a feature, one or both languages in the pair must support it. For example, for text translation:
 
-- **Target-only**: `formality` is required only on the target language. Check that `"formality"` is present in the
-  target language's `features` array.
-- **Source-and-target**: `tag_handling` and `glossary` are required on both languages. Check that the feature is
-  present in *both* the source and target language's `features` arrays.
+- **Target-only**: `formality` only needs to be supported by the target language. Check that `"formality"` is
+  present in the target language's `features` array.
+- **Source-and-target**: `tag_handling` and `glossary` must be supported by both languages. Check that the
+  feature is present in *both* the source and target language's `features` arrays.
 
-Source-only features are also supported by the schema, though none exist currently.
+Source-only features are also supported by the schema, and may be introduced in future products.
 
 In the documentation for API features that are supported for only a subset of languages, we specify
 which language feature value to check, and whether to check the source language, target language, or both.
 
 ## Retrieving products programmatically
 
 Use the `/v3/languages/products` endpoint to retrieve the list of products and their features programmatically.
-For each feature, the response indicates whether support is required on the source language, the target language,
-or both — allowing clients to determine feature availability for a language pair by checking the appropriate
-`features` arrays.
+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` arrays.
 
 ```sh
 curl -X GET 'https://api.deepl.com/v3/languages/products' \

api-reference/openapi.yaml

@@ -1955,10 +1955,10 @@ paths:
       description: |-
         Returns all DeepL API products, including the API endpoints they expose, and the features they support.
 
-        For each feature, the response indicates whether support is required on the source language
-        (`required_on_source`), the target language (`required_on_target`), or both. This allows
-        clients to determine feature availability for a language pair by checking the appropriate language's
-        `features` array returned by `GET /v3/languages`.
+        For each feature, the response indicates which languages must support it for the feature to be
+        available — source only (`required_on_source`), target only (`required_on_target`), or both.
+        This allows clients to determine feature availability for a language pair by checking the
+        appropriate language's `features` array returned by `GET /v3/languages`.
       responses:
         200:
           description: JSON array where each item represents a DeepL API product.
@@ -1995,8 +1995,8 @@ paths:
                         - v2/translate
                     features:
                       description: |-
-                        Features supported by this product. Each feature indicates whether support is
-                        required on the source language, the target language, or both.
+                        Features supported by this product. Each feature indicates which languages
+                        must support it for the feature to be available — source, target, or both.
                       type: array
                       items:
                         type: object
@@ -2014,10 +2014,10 @@ paths:
                               - writing_style
                               - tone
                           required_on_source:
-                            description: Whether support for this feature is required on the source language. Defaults to `false` if absent.
+                            description: If `true`, the source language must support this feature for it to be available. Defaults to `false` if absent.
                             type: boolean
                           required_on_target:
-                            description: Whether support for this feature is required on the target language. Defaults to `false` if absent.
+                            description: If `true`, the target language must support this feature for it to be available. Defaults to `false` if absent.
                             type: boolean
               example:
                 - name: translate_text