From cbda9d443d072f7c78c8f71017b21e0d7b3ebc41 Mon Sep 17 00:00:00 2001 From: Fabian Helpenstein Date: Wed, 28 Oct 2026 07:39:58 +0100 Subject: [PATCH] docs(glossaries): document language variant targets for v3 glossaries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a MultilingualGlossaryTargetLanguage schema for the v3 glossary endpoints that adds the twelve target variants (de-CH, de-DE, en-GB, en-US, es-419, es-ES, fr-CA, fr-FR, pt-BR, pt-PT, zh-Hans, zh-Hant) to the base languages. It describes base versus exact-variant applicability and the one-family-one-form rule with its 400 error. The v2 glossary schemas keep the base-only list. Add an October 26 changelog entry for the release. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- api-reference/openapi.json | 61 +++++++++++++++-- api-reference/openapi.yaml | 71 ++++++++++++++++++-- docs/resources/roadmap-and-release-notes.mdx | 6 ++ 3 files changed, 128 insertions(+), 10 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 0c71a295..171df28f 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -2174,7 +2174,7 @@ "in": "query", "required": true, "schema": { - "$ref": "#/components/schemas/GlossaryTargetLanguage" + "$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage" } } ], @@ -2269,7 +2269,7 @@ "in": "query", "required": true, "schema": { - "$ref": "#/components/schemas/GlossaryTargetLanguage" + "$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage" } } ], @@ -9756,7 +9756,7 @@ "$ref": "#/components/schemas/GlossarySourceLanguage" }, "target_lang": { - "$ref": "#/components/schemas/GlossaryTargetLanguage" + "$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage" }, "entries": { "$ref": "#/components/schemas/GlossaryEntries" @@ -9880,6 +9880,57 @@ ], "example": "de" }, + "MultilingualGlossaryTargetLanguage": { + "type": "string", + "description": "The language in which the target texts in the dictionary are specified. Besides the base languages, the\ntarget can be one of these variants: `de-CH`, `de-DE`, `en-GB`, `en-US`, `es-419`, `es-ES`, `fr-CA`,\n`fr-FR`, `pt-BR`, `pt-PT`, `zh-Hans`, or `zh-Hant`. Source languages are always base languages. The current\nlist is returned by `GET /v3/languages?resource=glossary`.\n\nA dictionary with a base target, such as `de`, applies when translating into that language and any of its\nvariants. A dictionary with a variant target, such as `de-CH`, applies only when translating into that\nexact variant.\n\nWithin one glossary, each language family uses either the base language or its variants as targets, not\nboth. For example, `de-CH` and `de-DE` can be combined, but `de` and `de-DE` cannot. Adding a dictionary\nthat breaks this rule returns a 400 error.", + "enum": [ + "ar", + "bg", + "cs", + "da", + "de", + "de-CH", + "de-DE", + "el", + "en", + "en-GB", + "en-US", + "es", + "es-419", + "es-ES", + "et", + "fi", + "fr", + "fr-CA", + "fr-FR", + "he", + "hu", + "id", + "it", + "ja", + "ko", + "lt", + "lv", + "nb", + "nl", + "pl", + "pt", + "pt-BR", + "pt-PT", + "ro", + "ru", + "sk", + "sl", + "sv", + "tr", + "uk", + "vi", + "zh", + "zh-Hans", + "zh-Hant" + ], + "example": "de" + }, "SpokenTermsId": { "type": "string", "format": "uuid", @@ -9977,7 +10028,7 @@ "$ref": "#/components/schemas/GlossarySourceLanguage" }, "target_lang": { - "$ref": "#/components/schemas/GlossaryTargetLanguage" + "$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage" }, "entries": { "$ref": "#/components/schemas/GlossaryEntries" @@ -10005,7 +10056,7 @@ "$ref": "#/components/schemas/GlossarySourceLanguage" }, "target_lang": { - "$ref": "#/components/schemas/GlossaryTargetLanguage" + "$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage" }, "entry_count": { "$ref": "#/components/schemas/GlossaryEntryCount" diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index b1cd9fac..a1a7ef5e 100644 --- a/api-reference/openapi.yaml +++ b/api-reference/openapi.yaml @@ -1740,7 +1740,7 @@ paths: in: query required: true schema: - $ref: '#/components/schemas/GlossaryTargetLanguage' + $ref: '#/components/schemas/MultilingualGlossaryTargetLanguage' responses: '200': description: The entries in tsv, wrapped in a JSON object. @@ -1801,7 +1801,7 @@ paths: in: query required: true schema: - $ref: '#/components/schemas/GlossaryTargetLanguage' + $ref: '#/components/schemas/MultilingualGlossaryTargetLanguage' responses: '204': description: Returns no content upon success. @@ -7224,7 +7224,7 @@ components: source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: - $ref: '#/components/schemas/GlossaryTargetLanguage' + $ref: '#/components/schemas/MultilingualGlossaryTargetLanguage' entries: $ref: '#/components/schemas/GlossaryEntries' entries_format: @@ -7335,6 +7335,67 @@ components: - vi - zh example: de + MultilingualGlossaryTargetLanguage: + type: string + description: |- + The language in which the target texts in the dictionary are specified. Besides the base languages, the + target can be one of these variants: `de-CH`, `de-DE`, `en-GB`, `en-US`, `es-419`, `es-ES`, `fr-CA`, + `fr-FR`, `pt-BR`, `pt-PT`, `zh-Hans`, or `zh-Hant`. Source languages are always base languages. The current + list is returned by `GET /v3/languages?resource=glossary`. + + A dictionary with a base target, such as `de`, applies when translating into that language and any of its + variants. A dictionary with a variant target, such as `de-CH`, applies only when translating into that + exact variant. + + Within one glossary, each language family uses either the base language or its variants as targets, not + both. For example, `de-CH` and `de-DE` can be combined, but `de` and `de-DE` cannot. Adding a dictionary + that breaks this rule returns a 400 error. + enum: + - ar + - bg + - cs + - da + - de + - de-CH + - de-DE + - el + - en + - en-GB + - en-US + - es + - es-419 + - es-ES + - et + - fi + - fr + - fr-CA + - fr-FR + - he + - hu + - id + - it + - ja + - ko + - lt + - lv + - nb + - nl + - pl + - pt + - pt-BR + - pt-PT + - ro + - ru + - sk + - sl + - sv + - tr + - uk + - vi + - zh + - zh-Hans + - zh-Hant + example: de SpokenTermsId: type: string format: uuid @@ -7414,7 +7475,7 @@ components: source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: - $ref: '#/components/schemas/GlossaryTargetLanguage' + $ref: '#/components/schemas/MultilingualGlossaryTargetLanguage' entries: $ref: '#/components/schemas/GlossaryEntries' entries_format: @@ -7432,7 +7493,7 @@ components: source_lang: $ref: '#/components/schemas/GlossarySourceLanguage' target_lang: - $ref: '#/components/schemas/GlossaryTargetLanguage' + $ref: '#/components/schemas/MultilingualGlossaryTargetLanguage' entry_count: $ref: '#/components/schemas/GlossaryEntryCount' OutlineDetectionOption: diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index b017910b..cb0efa15 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -9,6 +9,12 @@ rss: true +## October 26 - Glossaries for Language Variants +- A [glossary](/docs/customize/managing-glossaries) holds dictionaries that map source terms to target terms, one dictionary per language pair. A dictionary could previously only target a base language such as `pt`, and it applied to every variant of that language. You can now also create a dictionary for a specific variant, such as `pt-BR` or `pt-PT`, so terminology that differs between variants stays separate within one glossary. +- Set the variant code as the dictionary's `target_lang` in the [v3 glossary endpoints](/api-reference/multilingual-glossaries/create-a-glossary). Supported variant targets are `de-CH`, `de-DE`, `en-GB`, `en-US`, `es-419`, `es-ES`, `fr-CA`, `fr-FR`, `pt-BR`, `pt-PT`, `zh-Hans`, and `zh-Hant`. Source languages stay base languages. The current list is returned by [`GET /v3/languages?resource=glossary`](/docs/languages/using-the-languages-api). +- A dictionary with a base target keeps applying to all variants of that language. A variant dictionary applies only when the request's `target_lang` is that exact variant. +- Within one glossary, each language family uses either the base language or its variants as targets, not both. For example, `de-CH` and `de-DE` can be combined, but `de` and `de-DE` can't. Requests that break this rule return a 400 error. + ## October 20 - Style Profiles - A [style profile](/docs/customize/using-style-profiles) bundles the glossaries, style rule lists, and translation memories you use together under a single ID. Pass one `style_profile_id` in [`/v2/translate`](/api-reference/translate/request-translation) or [`/v2/document`](/api-reference/document/upload-and-translate-a-document) requests instead of the individual customization parameters, and update the profile when the bundle changes instead of your integration. - DeepL applies the components that fit each request: the glossaries for the language pair, the style rule list for the target language, and the translation memory for the source language. A profile can't be combined with `glossary_id`, `glossary_ids`, `style_id`, `translation_memory_id`, `translation_memory_threshold`, or `custom_instructions` in the same request.