From cd163a48f8309a1b4209da91845690629da9a765 Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Thu, 30 Apr 2026 13:38:56 -0500 Subject: [PATCH 1/8] Add how-to guide: applying customizations to variant target languages New guide covering how glossaries and style rules must be created with root language codes but can be applied to any variant in /translate calls. Co-Authored-By: Claude Sonnet 4.6 --- docs.json | 1 + .../customizations-for-variants.mdx | 126 ++++++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx diff --git a/docs.json b/docs.json index e84fa7d..981c639 100644 --- a/docs.json +++ b/docs.json @@ -58,6 +58,7 @@ "docs/learning-how-tos/examples-and-guides/translation-beginners-guide", "docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter", "docs/learning-how-tos/examples-and-guides/translating-between-variants", + "docs/learning-how-tos/examples-and-guides/customizations-for-variants", "docs/learning-how-tos/examples-and-guides/placeholder-tags", "docs/best-practices/language-detection" ], diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx new file mode 100644 index 0000000..3794496 --- /dev/null +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -0,0 +1,126 @@ +--- +title: "How to Apply Customizations to Variants" +description: "Learn how to apply glossaries and style rules when translating into language variants like FR-CA or EN-GB." +public: true +--- + +## Glossaries + +### Creation — root codes only + +Glossaries must be created using the root/base language code. Attempting to create a glossary with a variant code (e.g. `zh-Hant`, `pt-BR`, `fr-CA`) will fail. Use the base code instead: + +| Use this | Not this | +|---|---| +| `zh` | `zh-Hant`, `zh-Hans` | +| `pt` | `pt-BR`, `pt-PT` | +| `fr` | `fr-CA`, `fr-CH` | +| `de` | `de-CH` | +| `it` | `it-CH` | +| `es` | `es-ES`, `es-419` | + +### Application — variants are supported + +Once a glossary is created with a root code, it can be applied when translating into any variant of that language. The `target_lang` in the `/translate` call can be a variant, and the root glossary will be picked up automatically. + +**Example — creating a `zh` glossary, then applying it when translating into `zh-Hant`:** + +```python +import deepl + +translator = deepl.Translator("YOUR_AUTH_KEY") + +# Step 1: Create glossary using root code +glossary = translator.create_glossary( + "My Chinese Glossary", + source_lang="EN", + target_lang="ZH", # root code — not ZH-HANS or ZH-HANT + entries={"product": "产品", "customer": "客户"} +) + +# Step 2: Pass the glossary ID when translating into a variant +result = translator.translate_text( + "We value every customer.", + source_lang="EN", + target_lang="ZH-HANT", # variant target — glossary still applies + glossary=glossary.glossary_id # pass the ID of the root-code glossary +) + +print(result.text) +# 我們重視每一位客戶。 +``` + +The same pattern works for Portuguese: + +```python +# Glossary created with root code "PT" +glossary = translator.create_glossary( + "Portuguese Glossary", + source_lang="EN", + target_lang="PT", # root code + entries={"invoice": "fatura"} +) + +# Pass the same glossary ID to either variant +result_br = translator.translate_text( + "Please send the invoice.", + source_lang="EN", + target_lang="PT-BR", + glossary=glossary.glossary_id +) + +result_pt = translator.translate_text( + "Please send the invoice.", + source_lang="EN", + target_lang="PT-PT", + glossary=glossary.glossary_id +) + +print(result_br.text) # Favor enviar a fatura. +print(result_pt.text) # Por favor, envie a fatura. +``` + +--- + +## Style rules + +### Creation — root codes only + +Style rules cannot be created for variant codes — attempting to create one for `fr-CA`, `es-419`, or `de-CH` via the API returns a "language not supported" error. Use the root code only. + +Style rules for creation are currently supported for: `en`, `de`, `fr`, `es`, `it`, `ja`, `ko`, `zh`. With the Q2 release, Tier 2/3 languages (`vi`, `nl`, `ar`, `pt`, etc.) are being added for root-code style rule creation. + +### Application — variants are supported + +Once created under a root code, a style rule's `style_id` can be passed in a `/translate` call targeting any variant of that language: + +```python +# Style rule created for "FR" root code +# Can be applied when translating into FR-CA, FR-CH, or FR-FR + +result = translator.translate_text( + "Please review the attached document.", + source_lang="EN", + target_lang="FR-CA", # variant target + extra_params={"style_id": "your-style-rule-id"} # root FR style rule applies +) +``` + + +Variant codes are not selectable in the style rule creation UI — only root codes appear. You'll need to handle the mapping on your end, i.e. knowing which root style rule ID to pass for a given variant target. + + + +Some CAT tools may have their own logic that blocks passing a root language glossary or style rule when the target is a variant. This is a client-side implementation issue, not an API limitation — the DeepL API itself supports this pattern. + + +--- + +## Relevant links + +**Supported languages for creation (root codes):** +- Glossaries: [Supported languages](/docs/getting-started/supported-languages) — filter by "Glossary" +- Style rules: [Style rules API reference](/api-reference/style-rules) + +**Supported for application (translate call):** +- [/translate request reference](/api-reference/translate/request-translation) — see `glossary_id` and `style_id` parameters From 14350a799003c9010b183dc5149689f56347628e Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Fri, 1 May 2026 14:23:49 -0500 Subject: [PATCH 2/8] Update variant glossary examples with invoice/nota fiscal use case Co-Authored-By: Claude Sonnet 4.6 --- .../customizations-for-variants.mdx | 29 ++++++++++++------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx index 3794496..0188927 100644 --- a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -50,34 +50,41 @@ print(result.text) # 我們重視每一位客戶。 ``` -The same pattern works for Portuguese: +A practical example is "invoice" in Portuguese. Without a glossary, DeepL returns `"fatura"` for both PT-BR and PT-PT. But in Brazil, the legally correct term is `"nota fiscal"` — a glossary enforces that distinction: ```python -# Glossary created with root code "PT" -glossary = translator.create_glossary( - "Portuguese Glossary", +# PT-BR glossary: enforce the Brazilian legal term +glossary_br = translator.create_glossary( + "PT-BR Invoice Glossary", + source_lang="EN", + target_lang="PT", # root code + entries={"invoice": "nota fiscal"} +) + +# PT-PT glossary: keep the standard European term +glossary_pt = translator.create_glossary( + "PT-PT Invoice Glossary", source_lang="EN", target_lang="PT", # root code entries={"invoice": "fatura"} ) -# Pass the same glossary ID to either variant result_br = translator.translate_text( - "Please send the invoice.", + "Your invoice is ready to view.", source_lang="EN", target_lang="PT-BR", - glossary=glossary.glossary_id + glossary=glossary_br.glossary_id ) result_pt = translator.translate_text( - "Please send the invoice.", + "Your invoice is ready to view.", source_lang="EN", target_lang="PT-PT", - glossary=glossary.glossary_id + glossary=glossary_pt.glossary_id ) -print(result_br.text) # Favor enviar a fatura. -print(result_pt.text) # Por favor, envie a fatura. +print(result_br.text) # Sua nota fiscal está pronta para ser visualizada. +print(result_pt.text) # A sua fatura está pronta a ser visualizada. ``` --- From 3489936fff578054691a98502a0ce295933b439b Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Fri, 1 May 2026 16:39:38 -0500 Subject: [PATCH 3/8] Apply docs-review must-fixes to customizations-for-variants guide - Add orientation paragraph and "This guide shows you:" summary - Define "root code" on first use - Remove internal Q2/Tier language references - Bold table headers and add alignment specifiers - Add intro sentences before each code block - Replace Relevant links section with inline contextual links - Condense Warning callout and move to top Co-Authored-By: Claude Sonnet 4.6 --- .../customizations-for-variants.mdx | 63 +++++++++---------- 1 file changed, 28 insertions(+), 35 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx index 0188927..713d3fe 100644 --- a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -4,14 +4,25 @@ description: "Learn how to apply glossaries and style rules when translating int public: true --- +DeepL supports regional language variants such as `PT-BR` vs `PT-PT`, or `FR-CA` vs `FR-FR`. When applying customizations like glossaries and style rules, there is an important distinction: both must be **created** using the root language code, but can be **applied** to any variant in your `/translate` call. + +**This guide shows you:** +- Why customizations must be created with root codes (e.g. `PT`, `FR`) and not variant codes +- How to pass a root-code glossary or style rule when translating into a variant target +- A practical example of using variant-specific glossaries to enforce locale-appropriate terminology + + +Some CAT tools may block passing a root-code glossary or style rule when the target is a variant. This is a client-side limitation, not an API restriction — the DeepL API fully supports this pattern. + + ## Glossaries -### Creation — root codes only +### Creation: root codes only -Glossaries must be created using the root/base language code. Attempting to create a glossary with a variant code (e.g. `zh-Hant`, `pt-BR`, `fr-CA`) will fail. Use the base code instead: +DeepL distinguishes between root language codes (e.g. `pt`) and regional variant codes (e.g. `pt-BR`). Glossaries must be created with the root code — attempting to create one with a variant code will fail. See [supported glossary languages](/docs/getting-started/supported-languages) for the full list. -| Use this | Not this | -|---|---| +| **Use this** | **Not this** | +|:---|:---| | `zh` | `zh-Hant`, `zh-Hans` | | `pt` | `pt-BR`, `pt-PT` | | `fr` | `fr-CA`, `fr-CH` | @@ -19,11 +30,11 @@ Glossaries must be created using the root/base language code. Attempting to crea | `it` | `it-CH` | | `es` | `es-ES`, `es-419` | -### Application — variants are supported +### Application: variants are supported -Once a glossary is created with a root code, it can be applied when translating into any variant of that language. The `target_lang` in the `/translate` call can be a variant, and the root glossary will be picked up automatically. +Once a glossary is created with a root code, pass its ID in the `/translate` call with a variant `target_lang` — the glossary applies automatically. See the [`glossary_id` parameter](/api-reference/translate/request-translation) in the translate reference. -**Example — creating a `zh` glossary, then applying it when translating into `zh-Hant`:** +The following example creates a `ZH` glossary and applies it when translating into `ZH-HANT`: ```python import deepl @@ -43,14 +54,14 @@ result = translator.translate_text( "We value every customer.", source_lang="EN", target_lang="ZH-HANT", # variant target — glossary still applies - glossary=glossary.glossary_id # pass the ID of the root-code glossary + glossary=glossary.glossary_id ) print(result.text) # 我們重視每一位客戶。 ``` -A practical example is "invoice" in Portuguese. Without a glossary, DeepL returns `"fatura"` for both PT-BR and PT-PT. But in Brazil, the legally correct term is `"nota fiscal"` — a glossary enforces that distinction: +Glossaries are also useful for enforcing locale-specific terminology that DeepL wouldn't produce by default. Without a glossary, DeepL returns `"fatura"` for "invoice" in both `PT-BR` and `PT-PT`. In Brazil, the legally correct term is `"nota fiscal"` — a separate glossary per variant enforces the distinction: ```python # PT-BR glossary: enforce the Brazilian legal term @@ -91,43 +102,25 @@ print(result_pt.text) # A sua fatura está pronta a ser visualizada. ## Style rules -### Creation — root codes only +### Creation: root codes only -Style rules cannot be created for variant codes — attempting to create one for `fr-CA`, `es-419`, or `de-CH` via the API returns a "language not supported" error. Use the root code only. +Style rules follow the same constraint — they cannot be created for variant codes. Attempting to create a style rule for `fr-CA`, `es-419`, or `de-CH` returns a "language not supported" error. Use the root code only. See the [style rules reference](/api-reference/style-rules) for supported languages. -Style rules for creation are currently supported for: `en`, `de`, `fr`, `es`, `it`, `ja`, `ko`, `zh`. With the Q2 release, Tier 2/3 languages (`vi`, `nl`, `ar`, `pt`, etc.) are being added for root-code style rule creation. +### Application: variants are supported -### Application — variants are supported +Once created under a root code, pass the style rule's `style_id` in a `/translate` call targeting any variant of that language. See the [`style_id` parameter](/api-reference/translate/request-translation) in the translate reference. -Once created under a root code, a style rule's `style_id` can be passed in a `/translate` call targeting any variant of that language: +The following example applies a style rule created for `FR` when translating into `FR-CA`: ```python -# Style rule created for "FR" root code -# Can be applied when translating into FR-CA, FR-CH, or FR-FR - result = translator.translate_text( "Please review the attached document.", source_lang="EN", - target_lang="FR-CA", # variant target - extra_params={"style_id": "your-style-rule-id"} # root FR style rule applies + target_lang="FR-CA", # variant target — root FR style rule applies + extra_params={"style_id": "your-style-rule-id"} ) ``` -Variant codes are not selectable in the style rule creation UI — only root codes appear. You'll need to handle the mapping on your end, i.e. knowing which root style rule ID to pass for a given variant target. +Variant codes are not selectable in the style rule creation UI — only root codes appear. You'll need to map the correct root style rule ID to each variant target on your end. - - -Some CAT tools may have their own logic that blocks passing a root language glossary or style rule when the target is a variant. This is a client-side implementation issue, not an API limitation — the DeepL API itself supports this pattern. - - ---- - -## Relevant links - -**Supported languages for creation (root codes):** -- Glossaries: [Supported languages](/docs/getting-started/supported-languages) — filter by "Glossary" -- Style rules: [Style rules API reference](/api-reference/style-rules) - -**Supported for application (translate call):** -- [/translate request reference](/api-reference/translate/request-translation) — see `glossary_id` and `style_id` parameters From 8b4bc0b5f989596bf71c7f0642dd400923b8d169 Mon Sep 17 00:00:00 2001 From: Parvati Mani Date: Mon, 4 May 2026 12:05:25 -0500 Subject: [PATCH 4/8] Apply second-round docs-review must-fixes to customizations-for-variants - Fix filler intro sentence before second code block - Make all code blocks self-contained with imports and setup - Add sample output to style rules example - Add parallel root-code table to Style rules Creation section - Remove em-dash from Note callout - Add Next steps section Co-Authored-By: Claude Sonnet 4.6 --- .../customizations-for-variants.mdx | 49 +++++++++++++++---- 1 file changed, 40 insertions(+), 9 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx index 713d3fe..121ad8c 100644 --- a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -61,25 +61,29 @@ print(result.text) # 我們重視每一位客戶。 ``` -Glossaries are also useful for enforcing locale-specific terminology that DeepL wouldn't produce by default. Without a glossary, DeepL returns `"fatura"` for "invoice" in both `PT-BR` and `PT-PT`. In Brazil, the legally correct term is `"nota fiscal"` — a separate glossary per variant enforces the distinction: +The following example uses different terms for "invoice" in Brazilian and European Portuguese: ```python -# PT-BR glossary: enforce the Brazilian legal term +import deepl + +translator = deepl.Translator("YOUR_AUTH_KEY") + +# Step 1: Create a separate glossary for each variant, both using the root code glossary_br = translator.create_glossary( "PT-BR Invoice Glossary", source_lang="EN", - target_lang="PT", # root code + target_lang="PT", # root code — not PT-BR entries={"invoice": "nota fiscal"} ) -# PT-PT glossary: keep the standard European term glossary_pt = translator.create_glossary( "PT-PT Invoice Glossary", source_lang="EN", - target_lang="PT", # root code + target_lang="PT", # root code — not PT-PT entries={"invoice": "fatura"} ) +# Step 2: Pass each glossary ID to its corresponding variant result_br = translator.translate_text( "Your invoice is ready to view.", source_lang="EN", @@ -102,9 +106,20 @@ print(result_pt.text) # A sua fatura está pronta a ser visualizada. ## Style rules +[Style rules](/api-reference/style-rules) let you define writing preferences that are applied consistently across translations. They follow the same root-code constraint as glossaries. + ### Creation: root codes only -Style rules follow the same constraint — they cannot be created for variant codes. Attempting to create a style rule for `fr-CA`, `es-419`, or `de-CH` returns a "language not supported" error. Use the root code only. See the [style rules reference](/api-reference/style-rules) for supported languages. +Style rules cannot be created for variant codes — the same root-code constraint applies as for glossaries. Attempting to create a style rule for a variant code (e.g. `fr-CA`, `es-419`) returns a "language not supported" error. + +| **Use this** | **Not this** | +|:---|:---| +| `fr` | `fr-CA`, `fr-CH` | +| `es` | `es-ES`, `es-419` | +| `de` | `de-CH` | +| `pt` | `pt-BR`, `pt-PT` | + +See the [style rules reference](/api-reference/style-rules) for the full list of supported languages. ### Application: variants are supported @@ -113,14 +128,30 @@ Once created under a root code, pass the style rule's `style_id` in a `/translat The following example applies a style rule created for `FR` when translating into `FR-CA`: ```python +import deepl + +translator = deepl.Translator("YOUR_AUTH_KEY") + result = translator.translate_text( "Please review the attached document.", source_lang="EN", - target_lang="FR-CA", # variant target — root FR style rule applies - extra_params={"style_id": "your-style-rule-id"} + target_lang="FR-CA", # variant target — root FR style rule applies + extra_params={"style_id": "your-style-rule-id"} # style_id is a top-level API parameter ) + +print(result.text) +# Veuillez examiner le document ci-joint. ``` -Variant codes are not selectable in the style rule creation UI — only root codes appear. You'll need to map the correct root style rule ID to each variant target on your end. +Only root codes appear in the style rule creation UI. You'll need to map the correct root style rule ID to each variant target on your end. + +--- + +## Next steps + +- **Apply glossaries in practice:** See [Glossaries in the real world](/docs/learning-how-tos/examples-and-guides/glossaries-in-the-real-world) for a full worked example +- **Translate between variants:** Learn about the Write API and style rules in [How to translate between language variants](/docs/learning-how-tos/examples-and-guides/translating-between-variants) +- **Manage style rules:** Explore the [style rules API reference](/api-reference/style-rules) to create and retrieve style rules +- **Improve translation quality:** See how [the context parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) can further refine your translations From 1815cbb6ffc20b2a7027ea6184f531d6c2499bee Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Wed, 6 May 2026 16:15:18 -0400 Subject: [PATCH 5/8] Revise customizations guide for language variants Updated the title and description for clarity, refined language around customizations, and added sections on creating and applying customizations to language variants. --- .../customizations-for-variants.mdx | 92 ++----------------- 1 file changed, 10 insertions(+), 82 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx index 121ad8c..a56ff4d 100644 --- a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -1,25 +1,19 @@ --- -title: "How to Apply Customizations to Variants" +title: "How to Apply Customizations to Language Variants" description: "Learn how to apply glossaries and style rules when translating into language variants like FR-CA or EN-GB." public: true --- -DeepL supports regional language variants such as `PT-BR` vs `PT-PT`, or `FR-CA` vs `FR-FR`. When applying customizations like glossaries and style rules, there is an important distinction: both must be **created** using the root language code, but can be **applied** to any variant in your `/translate` call. +DeepL supports regional language variants such as `PT-BR` vs `PT-PT`, or `FR-CA` vs `FR-FR`. When applying customizations like glossaries and style rules, customizations must be created using the root language code, but can be applied to any variant of that language. **This guide shows you:** - Why customizations must be created with root codes (e.g. `PT`, `FR`) and not variant codes - How to pass a root-code glossary or style rule when translating into a variant target - A practical example of using variant-specific glossaries to enforce locale-appropriate terminology - -Some CAT tools may block passing a root-code glossary or style rule when the target is a variant. This is a client-side limitation, not an API restriction — the DeepL API fully supports this pattern. - +## Creating a customization for a language -## Glossaries - -### Creation: root codes only - -DeepL distinguishes between root language codes (e.g. `pt`) and regional variant codes (e.g. `pt-BR`). Glossaries must be created with the root code — attempting to create one with a variant code will fail. See [supported glossary languages](/docs/getting-started/supported-languages) for the full list. +DeepL distinguishes between root language codes (e.g. `pt`) and language variant codes (e.g. `pt-BR`). Customizations like glossaries and style rules must be created with the root code. Attempting to create one with a variant code will fail. | **Use this** | **Not this** | |:---|:---| @@ -30,38 +24,13 @@ DeepL distinguishes between root language codes (e.g. `pt`) and regional variant | `it` | `it-CH` | | `es` | `es-ES`, `es-419` | -### Application: variants are supported - -Once a glossary is created with a root code, pass its ID in the `/translate` call with a variant `target_lang` — the glossary applies automatically. See the [`glossary_id` parameter](/api-reference/translate/request-translation) in the translate reference. +See [supported glossary languages](/docs/getting-started/supported-languages) for the full list. -The following example creates a `ZH` glossary and applies it when translating into `ZH-HANT`: +## Applying a customization to a language variant -```python -import deepl +Once a customization is created with a root language code, pass its ID in the `/translate` call with a variant `target_lang`. -translator = deepl.Translator("YOUR_AUTH_KEY") - -# Step 1: Create glossary using root code -glossary = translator.create_glossary( - "My Chinese Glossary", - source_lang="EN", - target_lang="ZH", # root code — not ZH-HANS or ZH-HANT - entries={"product": "产品", "customer": "客户"} -) - -# Step 2: Pass the glossary ID when translating into a variant -result = translator.translate_text( - "We value every customer.", - source_lang="EN", - target_lang="ZH-HANT", # variant target — glossary still applies - glossary=glossary.glossary_id -) - -print(result.text) -# 我們重視每一位客戶。 -``` - -The following example uses different terms for "invoice" in Brazilian and European Portuguese: +The following example creates and applies 2 glossaries to use different terms for "invoice" in Brazilian and European Portuguese: ```python import deepl @@ -102,50 +71,9 @@ print(result_br.text) # Sua nota fiscal está pronta para ser visualizada. print(result_pt.text) # A sua fatura está pronta a ser visualizada. ``` ---- - -## Style rules - -[Style rules](/api-reference/style-rules) let you define writing preferences that are applied consistently across translations. They follow the same root-code constraint as glossaries. - -### Creation: root codes only - -Style rules cannot be created for variant codes — the same root-code constraint applies as for glossaries. Attempting to create a style rule for a variant code (e.g. `fr-CA`, `es-419`) returns a "language not supported" error. - -| **Use this** | **Not this** | -|:---|:---| -| `fr` | `fr-CA`, `fr-CH` | -| `es` | `es-ES`, `es-419` | -| `de` | `de-CH` | -| `pt` | `pt-BR`, `pt-PT` | - -See the [style rules reference](/api-reference/style-rules) for the full list of supported languages. - -### Application: variants are supported - -Once created under a root code, pass the style rule's `style_id` in a `/translate` call targeting any variant of that language. See the [`style_id` parameter](/api-reference/translate/request-translation) in the translate reference. - -The following example applies a style rule created for `FR` when translating into `FR-CA`: - -```python -import deepl - -translator = deepl.Translator("YOUR_AUTH_KEY") - -result = translator.translate_text( - "Please review the attached document.", - source_lang="EN", - target_lang="FR-CA", # variant target — root FR style rule applies - extra_params={"style_id": "your-style-rule-id"} # style_id is a top-level API parameter -) - -print(result.text) -# Veuillez examiner le document ci-joint. -``` +## CAT Tools - -Only root codes appear in the style rule creation UI. You'll need to map the correct root style rule ID to each variant target on your end. - +Some CAT tools may prevent applying a glossary or style rule linked to a root code language when the target language is a variant. This is an incorrect limitation that does not reflect the DeepL API's behavior. You'll need to reach out to your CAT tool provider to request this restriction is removed. --- From 8e413ccd0cc3d7c76d50cf9eaf4366252daef409 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Wed, 6 May 2026 16:17:43 -0400 Subject: [PATCH 6/8] Apply suggestions from code review Co-authored-by: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> --- .../examples-and-guides/customizations-for-variants.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx index a56ff4d..0583d93 100644 --- a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -7,8 +7,8 @@ public: true DeepL supports regional language variants such as `PT-BR` vs `PT-PT`, or `FR-CA` vs `FR-FR`. When applying customizations like glossaries and style rules, customizations must be created using the root language code, but can be applied to any variant of that language. **This guide shows you:** -- Why customizations must be created with root codes (e.g. `PT`, `FR`) and not variant codes -- How to pass a root-code glossary or style rule when translating into a variant target +- How to create customizations using root language codes (e.g. `PT`, `FR`) +- How to pass a customization when translating into a variant target (e.g. `pt-BR`, `fr-CA`) - A practical example of using variant-specific glossaries to enforce locale-appropriate terminology ## Creating a customization for a language From 3349b5c514608ffe353ea2fd342303e049c933f6 Mon Sep 17 00:00:00 2001 From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> Date: Wed, 6 May 2026 16:18:06 -0400 Subject: [PATCH 7/8] Apply suggestions from code review Co-authored-by: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com> --- .../examples-and-guides/customizations-for-variants.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx index 0583d93..0884bdd 100644 --- a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -24,7 +24,7 @@ DeepL distinguishes between root language codes (e.g. `pt`) and language variant | `it` | `it-CH` | | `es` | `es-ES`, `es-419` | -See [supported glossary languages](/docs/getting-started/supported-languages) for the full list. +See [supported languages](/docs/getting-started/supported-languages) for the full list. ## Applying a customization to a language variant From 7a7a9b36d74367101ef668b6f1b00ab85fb0f291 Mon Sep 17 00:00:00 2001 From: Shir Goldberg Date: Wed, 6 May 2026 16:26:14 -0400 Subject: [PATCH 8/8] Split code example into separate titled blocks for create and apply steps Co-Authored-By: Claude Opus 4.6 (1M context) --- .../customizations-for-variants.mdx | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx index 0884bdd..97e50cc 100644 --- a/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx +++ b/docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx @@ -11,7 +11,7 @@ DeepL supports regional language variants such as `PT-BR` vs `PT-PT`, or `FR-CA` - How to pass a customization when translating into a variant target (e.g. `pt-BR`, `fr-CA`) - A practical example of using variant-specific glossaries to enforce locale-appropriate terminology -## Creating a customization for a language +## Creating a customization for a language DeepL distinguishes between root language codes (e.g. `pt`) and language variant codes (e.g. `pt-BR`). Customizations like glossaries and style rules must be created with the root code. Attempting to create one with a variant code will fail. @@ -26,18 +26,13 @@ DeepL distinguishes between root language codes (e.g. `pt`) and language variant See [supported languages](/docs/getting-started/supported-languages) for the full list. -## Applying a customization to a language variant - -Once a customization is created with a root language code, pass its ID in the `/translate` call with a variant `target_lang`. +The following example creates two glossaries to enforce different terms for "invoice" in Brazilian and European Portuguese. Both use the root language code `PT`: -The following example creates and applies 2 glossaries to use different terms for "invoice" in Brazilian and European Portuguese: - -```python +```python Example: Create glossaries with root language codes import deepl translator = deepl.Translator("YOUR_AUTH_KEY") -# Step 1: Create a separate glossary for each variant, both using the root code glossary_br = translator.create_glossary( "PT-BR Invoice Glossary", source_lang="EN", @@ -51,8 +46,13 @@ glossary_pt = translator.create_glossary( target_lang="PT", # root code — not PT-PT entries={"invoice": "fatura"} ) +``` + +## Applying a customization to a language variant + +Once a customization is created with a root language code, pass its ID in the `/translate` call with a variant `target_lang`: -# Step 2: Pass each glossary ID to its corresponding variant +```python Example: Apply glossaries to variant targets result_br = translator.translate_text( "Your invoice is ready to view.", source_lang="EN", @@ -71,7 +71,7 @@ print(result_br.text) # Sua nota fiscal está pronta para ser visualizada. print(result_pt.text) # A sua fatura está pronta a ser visualizada. ``` -## CAT Tools +## CAT tools Some CAT tools may prevent applying a glossary or style rule linked to a root code language when the target language is a variant. This is an incorrect limitation that does not reflect the DeepL API's behavior. You'll need to reach out to your CAT tool provider to request this restriction is removed.