DeepL
DeepL provides industry-leading machine translation with excellent quality for European languages. DeepL offers a free tier – see DeepL API pricing for current limits.
Setup
To use DeepL as your translation provider, add your API key to the global configuration:
return [
'johannschopplich.content-translator' => [
'DeepL' => [
'apiKey' => env('DEEPL_API_KEY')
]
]
];
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.
To set custom request options for the DeepL API, add them to the plugin's requestOptions configuration:
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'
]
]
]
];
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.Supported Languages
The plugin mirrors DeepL's own catalogue: 114 source languages and 125 target languages. See DeepL's 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)
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.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:
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.