Global Configuration
Kirby Content Translator can be configured globally in your config.php
file. This allows you to set default options that apply to all instances of the plugin, 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
You can set global defaults that apply to both view buttons and sections. These can be overridden in individual blueprints. For example, 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
v3.7.0+ Batch Concurrency
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
]
]