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 sections
• import – Enable/disable import functionality
• importFrom – Control import direction
• batch – Enable/disable batch translation
• title – Include title in translation
• slug – Include slug in translation
• confirm – Show confirmation dialogs
• fieldTypes – Which field types to translate
• includeFields – Specific fields to include
• excludeFields – Specific fields to exclude
• kirbyTags – 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:

1. Global configuration (in config.php)
2. 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.

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
    ]
]