How to Apply Customizations to Language Variants

Learn how to apply glossaries and style rules when translating into language variants like FR-CA or EN-GB.

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 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:

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:

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 for a full worked example
• Translate between variants: Learn about the Write API and style rules in How to translate between language variants
• Manage style rules: Explore the style rules API reference to create and retrieve style rules
• Improve translation quality: See how the context parameter can further refine your translations