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

Merged
fabicious merged 2 commits into from
Nov 3, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1df24c2
docs(glossaries): document language variant targets for v3 glossaries
fabicious Oct 28, 2026
0039429
docs(glossary): Update feed date
fabicious Nov 2, 2026
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 @@ -2187,7 +2187,7 @@
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
}
}
],
Expand Down Expand Up @@ -2282,7 +2282,7 @@
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
}
}
],
Expand Down Expand Up @@ -9769,7 +9769,7 @@
"$ref": "#/components/schemas/GlossarySourceLanguage"
},
"target_lang": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
},
"entries": {
"$ref": "#/components/schemas/GlossaryEntries"
Expand Down Expand Up @@ -9893,6 +9893,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 @@ -9990,7 +10041,7 @@
"$ref": "#/components/schemas/GlossarySourceLanguage"
},
"target_lang": {
"$ref": "#/components/schemas/GlossaryTargetLanguage"
"$ref": "#/components/schemas/MultilingualGlossaryTargetLanguage"
},
"entries": {
"$ref": "#/components/schemas/GlossaryEntries"
Expand Down Expand Up @@ -10018,7 +10069,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 @@ -1774,7 +1774,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 @@ -1835,7 +1835,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 @@ -7258,7 +7258,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 @@ -7369,6 +7369,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 @@ -7448,7 +7509,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 @@ -7466,7 +7527,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="November 2026">
## November 3 - 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.

## November 2 - Custom Instructions for Document Translation
- [Custom instructions](/docs/customize/custom-instructions) are natural language directives, such as "Use a friendly, diplomatic tone", that guide how DeepL translates. [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now accepts them in the `custom_instructions` parameter, as they already work in text translation.
- Send the instructions as a JSON array of strings in a single form field, for example `["Use a friendly, diplomatic tone"]`. The same limits as text translation apply: up to 10 instructions, each with a maximum of 300 characters.
Expand Down
Loading