Global Configuration

Configure Kirby Content Translator globally in your config.php file. This sets default configuration properties 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 Properties

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 properties 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 Properties

For detailed descriptions of each property, see the View Button & Section Configuration page. All local properties can be defined globally.

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