Skip to content

docs(glossaries): document language variant targets for v3 glossaries #477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fabicious wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(glossaries): document language variant targets for v3 glossaries #477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 56 additions & 5 deletions api-reference/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2174,7 +2174,7 @@
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
}
}
],
Expand Down Expand Up @@ -2269,7 +2269,7 @@
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
}
}
],
Expand Down Expand Up @@ -9756,7 +9756,7 @@
"$ref": "#/components/schemas/GlossarySourceLanguage"
},
"target_lang": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
},
"entries": {
"$ref": "#/components/schemas/GlossaryEntries"
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -9977,7 +10028,7 @@
"$ref": "#/components/schemas/GlossarySourceLanguage"
},
"target_lang": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
},
"entries": {
"$ref": "#/components/schemas/GlossaryEntries"
Expand Down Expand Up @@ -10005,7 +10056,7 @@
"$ref": "#/components/schemas/GlossarySourceLanguage"
},
"target_lang": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
},
"entry_count": {
"$ref": "#/components/schemas/GlossaryEntryCount"
Expand Down
71 changes: 66 additions & 5 deletions api-reference/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand Down
6 changes: 6 additions & 0 deletions docs/resources/roadmap-and-release-notes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@ rss: true
</Update>

<Update label="October 2026">
## October 26 - Glossaries for Language Variants

@BriannaDelgado BriannaDelgado Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you update the date?

- 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.
Expand Down
Loading