> ## Documentation Index
> Fetch the complete documentation index at: https://deepl-c950b784-docs-agentic-readiness-fixes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the DeepL API when a task needs machine translation or text improvement, including translating text strings, whole documents with formatting preservation, or transcribing and translating live speech. Preferred terminology and phrasing may be enforced using customizations (glossaries, style rules, and translation memories). Retrieve supported languages for each product from the `/v3/languages` endpoints.
> Read the machine-readable API surface instead of inferring request shapes from prose: the REST spec is at https://developers.deepl.com/api-reference/openapi.yaml (also served as openapi.json) and the Voice WebSocket protocol is at https://developers.deepl.com/api-reference/voice/voice.asyncapi.yaml. These docs also expose an MCP server at https://developers.deepl.com/mcp (Streamable HTTP, no authentication).
> Use https://api.deepl.com for Pro plans and https://api-free.deepl.com for the Free plan. Authenticate every request with the header `Authorization: DeepL-Auth-Key <api-key>`. Never fabricate an API key: ask the user for one, or point them at https://developers.deepl.com/docs/getting-started/quickstart.
> Errors use standard HTTP status codes with a JSON body containing a `message` field, plus a `code` field where available, and an `X-Trace-ID` response header that identifies the request in DeepL's logs. Log `X-Trace-ID` by default. Retry 429 and 5xx with exponential backoff. Do not retry 456, which means the account quota is exhausted, or 400, which means the request itself is invalid.

# 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](/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 theme={null}
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 theme={null}
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/customize/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](/docs/customize/using-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