Add how-to guide: applying customizations to variant target languages

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"
                 ],

docs/learning-how-tos/examples-and-guides/customizations-for-variants.mdx

@@ -0,0 +1,85 @@
+---
+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, customizations must be created using the root language code, but can be applied to any variant of that language.
+
+**This guide shows you:**
+- 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
+
+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** |
+|:---|:---|
+| `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` |
+
+See [supported languages](/docs/getting-started/supported-languages) for the full list.
+
+The following example creates two glossaries to enforce different terms for "invoice" in Brazilian and European Portuguese. Both use the root language code `PT`:
+
+```python Example: Create glossaries with root language codes
+import deepl
+
+translator = deepl.Translator("YOUR_AUTH_KEY")
+
+glossary_br = translator.create_glossary(
+    "PT-BR Invoice Glossary",
+    source_lang="EN",
+    target_lang="PT",        # root code — not PT-BR
+    entries={"invoice": "nota fiscal"}
+)
+
+glossary_pt = translator.create_glossary(
+    "PT-PT Invoice Glossary",
+    source_lang="EN",
+    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`:
+
+```python Example: Apply glossaries to variant targets
+result_br = translator.translate_text(
+    "Your invoice is ready to view.",
+    source_lang="EN",
+    target_lang="PT-BR",
+    glossary=glossary_br.glossary_id
+)
+
+result_pt = translator.translate_text(
+    "Your invoice is ready to view.",
+    source_lang="EN",
+    target_lang="PT-PT",
+    glossary=glossary_pt.glossary_id
+)
+
+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
+
+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. 
+
+---
+
+## 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