---
title: "DeepL"
description: "Translate via DeepL with native API support – tunable request options, language-code overrides, and a free tier."
canonical_url: "https://kirby.tools/docs/content-translator/providers/deepl"
---

# DeepL

> Translate via DeepL with native API support – tunable request options, language-code overrides, and a free tier.

[DeepL](https://www.deepl.com) provides industry-leading machine translation with excellent quality for European languages. DeepL offers a free tier – see [DeepL API pricing](https://www.deepl.com/pro-api) for current limits.

## Setup

To use DeepL as your translation provider, add your API key to the global configuration:

```php [config.php]
return [
    'johannschopplich.content-translator' => [
        'DeepL' => [
            'apiKey' => env('DEEPL_API_KEY')
        ]
    ]
];
```

<tip>

The plugin automatically detects whether you're using a free or pro API key and uses the appropriate endpoint.

</tip>

## Request Options

DeepL offers a variety of options to customize the text translation API endpoint. To learn more about the available options, please refer to the [DeepL translate text parameters](https://developers.deepl.com/docs/api-reference/translate#request-body-descriptions).

To set custom request options for the DeepL API, add them to the plugin's `requestOptions` configuration:

```php [config.php]
return [
    'johannschopplich.content-translator' => [
        'DeepL' => [
            // All available options can be found in the DeepL API documentation:
            // https://developers.deepl.com/docs/api-reference/translate#request-body-descriptions
            'requestOptions' => [
                // Lean towards formal language
                'formality' => 'more'
            ]
        ]
    ]
];
```

<note>

`text`, `source_lang`, and `target_lang` are ignored here – the texts and languages of the current translation always win. Use `targetLanguageOverrides` to pin a target code.

</note>

## Supported Languages

The plugin mirrors DeepL's own catalogue: 114 source languages and 125 target languages. See [DeepL's supported languages](https://developers.deepl.com/docs/getting-started/supported-languages) for the current list.

Regional variants exist as target languages only:

- German: Germany (DE-DE), Switzerland (DE-CH)
- English: British (EN-GB), American (EN-US)
- French: France (FR-FR), Canada (FR-CA)
- Portuguese: Brazilian (PT-BR), European (PT-PT)
- Spanish: European (ES), Latin American (ES-419)
- Chinese: Simplified (ZH-HANS), Traditional (ZH-HANT)

<tip>

Regional variants resolve from your Kirby language code first, then from its `LC_ALL` locale. A language code of `de-ch` receives `DE-CH`, and so does a plain `de` with the locale `de_CH.UTF-8`. The code wins when the two disagree, so a Swiss site keeps Swiss German on a server that only has `de_DE` installed.

</tip>

## Language Code Overrides

When your Kirby language code names no language DeepL supports, translation fails with a `LogicException` – its locale can only sharpen the code into a regional variant, never stand in for it. A `cn` language therefore stays unresolvable on a `zh_CN.UTF-8` server; map the code to a DeepL target code instead:

```php [config.php]
return [
    'johannschopplich.content-translator' => [
        'DeepL' => [
            'targetLanguageOverrides' => [
                // Kirby language code => DeepL target code
                'cn' => 'ZH-HANS',
                'no' => 'NB'
            ]
        ]
    ]
];
```

An override outranks both the language code and the locale, and isn't checked against the supported languages – so it also carries a code DeepL releases after this version.

Source languages follow the same mapping: a language overridden to `ZH-HANS` is sent as `ZH` when it acts as the source.

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>