Global Configuration
Configure Kirby Content Translator globally in your config.php file. This sets default options that apply to all plugin instances, including translation provider settings and default behavior for view buttons and sections.
Translation Provider Configuration
Either DeepL or a custom translation function must be configured for the plugin to work.
DeepL API Configuration
To use DeepL as your translation provider, set your API key in the global configuration:
return [
'johannschopplich.content-translator' => [
'DeepL' => [
'apiKey' => '<deepl-api-key>',
]
]
]
Custom Translation Function
For advanced use cases, you can provide a custom translation function:
return [
'johannschopplich.content-translator' => [
'translateFn' => function (string $text, string $targetLanguage, string $sourceLanguage = null) {
// Your custom translation implementation…
// It must return the translated text as a string
return $translatedText;
}
]
]
Global Default Options
Set global defaults that apply to both view buttons and sections. These can be overridden in individual blueprints. The following configuration sets DeepL as the translation provider and defines global defaults for field types, title translation, slug translation, confirmation dialogs, and KirbyTags translation:
return [
'johannschopplich.content-translator' => [
// Translation provider
'DeepL' => [
'apiKey' => env('DEEPL_API_KEY')
],
// Global default options for view buttons and sections
'fieldTypes' => [
'blocks',
'text',
'textarea'
],
'title' => true,
'slug' => true,
'confirm' => false,
'kirbyTags' => [
'link' => ['text', 'title'],
'image' => ['alt', 'caption'],
'file' => ['text', 'title']
]
]
]
Available View Button & Section Options
For detailed descriptions of each configuration option, see the View Button & Section Configuration page. All local configuration options can be defined globally.
label– Custom label for sectionsimport– Enable/disable import functionalityimportFrom– Control import directionbatch– Enable/disable batch translationtitle– Include title in translationslug– Include slug in translationconfirm– Show confirmation dialogsfieldTypes– Which field types to translateincludeFields– Specific fields to includeexcludeFields– Specific fields to excludekirbyTags– KirbyTags translation configuration
Batch Concurrency v3.7.0+
In batch translation mode, multiple languages are translated in parallel to improve performance. By default, up to 4 translations are processed concurrently to avoid hitting API rate limits.
If you encounter DeepL API rate limit errors, you can reduce the concurrency by setting the batchConcurrency option in your global configuration. For example, to limit concurrency to 2:
return [
'johannschopplich.content-translator' => [
'batchConcurrency' => 2
]
]
Configuration Precedence
Global configuration serves as the foundation, with more specific configurations overriding global defaults:
- Global configuration (in
config.php) - Section configuration (in blueprint sections) & view button props (in blueprint buttons – Kirby 5+ only)
For example, the following global configuration sets defaults for fieldTypes and confirm, which can be overridden in blueprints:
return [
'johannschopplich.content-translator' => [
'fieldTypes' => ['text', 'textarea'], // Global default
'confirm' => false, // Global default
]
]
In a blueprint, you can override these global defaults in both sections and buttons:
sections:
contentTranslator:
type: content-translator
fieldTypes: # Overrides global
- blocks
- text
- textarea
# confirm: false inherited from global
buttons:
content-translator:
confirm: true # Overrides global config
Custom Plugin Translations
If you prefer to overwrite the default translations of the plugin, you can do so by adding translations for your language in the languages directory of your Kirby installation.
translations.php for the full list of translation keys.For example, to change the translation of the import button to Synchronize in English, append the following translations array to the languages/en.php file:
return [
'code' => 'en',
'name' => 'English',
// ... Other language configuration
'translations' => [
'johannschopplich.content-translator.import' => 'Synchronize'
]
];
Panel View Button (Kirby 4 Only)

In Kirby 4, the Content Translator view button is automatically enabled. You can disable it globally by setting the viewButton option to false in your global configuration:
return [
'johannschopplich.content-translator' => [
'viewButton' => false // Disable the view button globally
]
]