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..713d3fe
--- /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
+---
+
+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
+
+<Warning>
+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.
+</Warning>
+
+## 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.
+
+| **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, 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.
+
+The following example creates a `ZH` glossary and applies 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
+)
+
+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:
+
+```python
+# 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"}
+)
+
+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.
+```
+
+---
+
+## Style rules
+
+### 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.
+
+### 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
+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"}
+)
+```
+
+<Note>
+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.
+</Note>