Skip to content

Commit 1df24c2

Browse files
fabiciousclaude
fabicious
and
claude
committed
docs(glossaries): document language variant targets for v3 glossaries
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 <noreply@anthropic.com>
1 parent 2ad0b0e commit 1df24c2

3 files changed

Lines changed: 128 additions & 10 deletions

File tree

‎api-reference/openapi.json‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2187,7 +2187,7 @@
21872187
"in": "query",
21882188
"required": true,
21892189
"schema": {
2190-
"$ref": "#/components/schemas/GlossaryTargetLanguage"
2190+
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
21912191
}
21922192
}
21932193
],
@@ -2282,7 +2282,7 @@
22822282
"in": "query",
22832283
"required": true,
22842284
"schema": {
2285-
"$ref": "#/components/schemas/GlossaryTargetLanguage"
2285+
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
22862286
}
22872287
}
22882288
],
@@ -9769,7 +9769,7 @@
97699769
"$ref": "#/components/schemas/GlossarySourceLanguage"
97709770
},
97719771
"target_lang": {
9772-
"$ref": "#/components/schemas/GlossaryTargetLanguage"
9772+
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
97739773
},
97749774
"entries": {
97759775
"$ref": "#/components/schemas/GlossaryEntries"
@@ -9893,6 +9893,57 @@
98939893
],
98949894
"example": "de"
98959895
},
9896+
"MultilingualGlossaryTargetLanguage": {
9897+
"type": "string",
9898+
"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.",
9899+
"enum": [
9900+
"ar",
9901+
"bg",
9902+
"cs",
9903+
"da",
9904+
"de",
9905+
"de-CH",
9906+
"de-DE",
9907+
"el",
9908+
"en",
9909+
"en-GB",
9910+
"en-US",
9911+
"es",
9912+
"es-419",
9913+
"es-ES",
9914+
"et",
9915+
"fi",
9916+
"fr",
9917+
"fr-CA",
9918+
"fr-FR",
9919+
"he",
9920+
"hu",
9921+
"id",
9922+
"it",
9923+
"ja",
9924+
"ko",
9925+
"lt",
9926+
"lv",
9927+
"nb",
9928+
"nl",
9929+
"pl",
9930+
"pt",
9931+
"pt-BR",
9932+
"pt-PT",
9933+
"ro",
9934+
"ru",
9935+
"sk",
9936+
"sl",
9937+
"sv",
9938+
"tr",
9939+
"uk",
9940+
"vi",
9941+
"zh",
9942+
"zh-Hans",
9943+
"zh-Hant"
9944+
],
9945+
"example": "de"
9946+
},
98969947
"SpokenTermsId": {
98979948
"type": "string",
98989949
"format": "uuid",
@@ -9990,7 +10041,7 @@
999010041
"$ref": "#/components/schemas/GlossarySourceLanguage"
999110042
},
999210043
"target_lang": {
9993-
"$ref": "#/components/schemas/GlossaryTargetLanguage"
10044+
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
999410045
},
999510046
"entries": {
999610047
"$ref": "#/components/schemas/GlossaryEntries"
@@ -10018,7 +10069,7 @@
1001810069
"$ref": "#/components/schemas/GlossarySourceLanguage"
1001910070
},
1002010071
"target_lang": {
10021-
"$ref": "#/components/schemas/GlossaryTargetLanguage"
10072+
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
1002210073
},
1002310074
"entry_count": {
1002410075
"$ref": "#/components/schemas/GlossaryEntryCount"

‎api-reference/openapi.yaml‎

Lines changed: 66 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1774,7 +1774,7 @@ paths:
17741774
in: query
17751775
required: true
17761776
schema:
1777-
$ref: '#/components/schemas/GlossaryTargetLanguage'
1777+
$ref: '#/components/schemas/MultilingualGlossaryTargetLanguage'
17781778
responses:
17791779
'200':
17801780
description: The entries in tsv, wrapped in a JSON object.
@@ -1835,7 +1835,7 @@ paths:
18351835
in: query
18361836
required: true
18371837
schema:
1838-
$ref: '#/components/schemas/GlossaryTargetLanguage'
1838+
$ref: '#/components/schemas/MultilingualGlossaryTargetLanguage'
18391839
responses:
18401840
'204':
18411841
description: Returns no content upon success.
@@ -7258,7 +7258,7 @@ components:
72587258
source_lang:
72597259
$ref: '#/components/schemas/GlossarySourceLanguage'
72607260
target_lang:
7261-
$ref: '#/components/schemas/GlossaryTargetLanguage'
7261+
$ref: '#/components/schemas/MultilingualGlossaryTargetLanguage'
72627262
entries:
72637263
$ref: '#/components/schemas/GlossaryEntries'
72647264
entries_format:
@@ -7369,6 +7369,67 @@ components:
73697369
- vi
73707370
- zh
73717371
example: de
7372+
MultilingualGlossaryTargetLanguage:
7373+
type: string
7374+
description: |-
7375+
The language in which the target texts in the dictionary are specified. Besides the base languages, the
7376+
target can be one of these variants: `de-CH`, `de-DE`, `en-GB`, `en-US`, `es-419`, `es-ES`, `fr-CA`,
7377+
`fr-FR`, `pt-BR`, `pt-PT`, `zh-Hans`, or `zh-Hant`. Source languages are always base languages. The current
7378+
list is returned by `GET /v3/languages?resource=glossary`.
7379+
7380+
A dictionary with a base target, such as `de`, applies when translating into that language and any of its
7381+
variants. A dictionary with a variant target, such as `de-CH`, applies only when translating into that
7382+
exact variant.
7383+
7384+
Within one glossary, each language family uses either the base language or its variants as targets, not
7385+
both. For example, `de-CH` and `de-DE` can be combined, but `de` and `de-DE` cannot. Adding a dictionary
7386+
that breaks this rule returns a 400 error.
7387+
enum:
7388+
- ar
7389+
- bg
7390+
- cs
7391+
- da
7392+
- de
7393+
- de-CH
7394+
- de-DE
7395+
- el
7396+
- en
7397+
- en-GB
7398+
- en-US
7399+
- es
7400+
- es-419
7401+
- es-ES
7402+
- et
7403+
- fi
7404+
- fr
7405+
- fr-CA
7406+
- fr-FR
7407+
- he
7408+
- hu
7409+
- id
7410+
- it
7411+
- ja
7412+
- ko
7413+
- lt
7414+
- lv
7415+
- nb
7416+
- nl
7417+
- pl
7418+
- pt
7419+
- pt-BR
7420+
- pt-PT
7421+
- ro
7422+
- ru
7423+
- sk
7424+
- sl
7425+
- sv
7426+
- tr
7427+
- uk
7428+
- vi
7429+
- zh
7430+
- zh-Hans
7431+
- zh-Hant
7432+
example: de
73727433
SpokenTermsId:
73737434
type: string
73747435
format: uuid
@@ -7448,7 +7509,7 @@ components:
74487509
source_lang:
74497510
$ref: '#/components/schemas/GlossarySourceLanguage'
74507511
target_lang:
7451-
$ref: '#/components/schemas/GlossaryTargetLanguage'
7512+
$ref: '#/components/schemas/MultilingualGlossaryTargetLanguage'
74527513
entries:
74537514
$ref: '#/components/schemas/GlossaryEntries'
74547515
entries_format:
@@ -7466,7 +7527,7 @@ components:
74667527
source_lang:
74677528
$ref: '#/components/schemas/GlossarySourceLanguage'
74687529
target_lang:
7469-
$ref: '#/components/schemas/GlossaryTargetLanguage'
7530+
$ref: '#/components/schemas/MultilingualGlossaryTargetLanguage'
74707531
entry_count:
74717532
$ref: '#/components/schemas/GlossaryEntryCount'
74727533
OutlineDetectionOption:

‎docs/resources/roadmap-and-release-notes.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,12 @@ rss: true
2525
- The request returns a `400` if the glossary has no dictionary for the detected language pair.
2626
- Document translation still requires `source_lang` with a glossary, and the DeepL client libraries currently require it too. See [use a glossary with automatic source language detection](/docs/customize/managing-glossaries#use-a-glossary-with-automatic-source-language-detection).
2727

28+
## October 26 - Glossaries for Language Variants
29+
- 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.
30+
- 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).
31+
- 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.
32+
- 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.
33+
2834
## October 20 - Style Profiles
2935
- 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.
3036
- 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.

0 commit comments

Comments
 (0)