Global Configuration

Translation Strategy

At least one translation strategy must be configured. Pick one below – the strategy option selects which one runs.

Defaults for Blueprint 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 strategy and defines global defaults for field types, title translation, slug translation, and KirbyTags translation:

return [
    'johannschopplich.content-translator' => [
        // Translation strategy
        'DeepL' => [
            'apiKey' => 'your-deepl-api-key'
        ],

        // Global default properties for view buttons and sections
        'fieldTypes' => [
            'blocks',
            'text',
            'textarea'
        ],
        'title' => true,
        'slug' => true,
        'kirbyTags' => [
            'link' => ['text', 'title'],
            'image' => ['alt', 'caption'],
            'file' => ['text', 'title']
        ]
    ]
];

Every view button and section property except cascade, label, systemPrompt, and theme can be set here as a project-wide default. The View Button & Section Configuration page describes each one. systemPrompt becomes ai.systemPrompt; cascade, label, and theme stay in the blueprint.

Global Options

strategy Mixed

Selects the translation strategy explicitly. Accepts a string preset, a closure, or a Strategy instance.

Default: none (the deprecated translateFn if one is configured, DeepL otherwise)

The Panel follows this option: a closure or Strategy instance enables the translation buttons without a DeepL.apiKey, and 'ai' makes AI translation the only strategy on offer. With a single strategy there is nothing to pick, so single-language translation starts without a dialog. A cascade still opens one, which states how many pages and files are saved directly.

return [
    'johannschopplich.content-translator' => [
        'strategy' => 'deepl', // or 'ai'
    ]
];

return [
    'johannschopplich.content-translator' => [
        'strategy' => function (string $text, string $target, ?string $source): string {
            return myTranslateApi($text, $target, $source);
        },
    ]
];

use App\Translation\MyApiStrategy;

return [
    'johannschopplich.content-translator' => [
        'strategy' => new MyApiStrategy(),
    ]
];

batchConcurrency Integer

Caps how many translations run in parallel – the languages of a batch run and the pages and files of a cascade alike.

Default: 2 (to avoid hitting API rate limits)

Lower it to 1 when the provider returns rate limit errors – the translations then run one after another:

return [
    'johannschopplich.content-translator' => [
        'batchConcurrency' => 1
    ]
];

coverage Mixed

Scopes the coverage dashboard in the Languages view to the pages a pages closure returns, or removes it with false. See Translation Coverage.

Default: true (the dashboard covers site()->index())

cache Mixed

Points the plugin's own cache at another driver, or turns it off. It backs the coverage rings and the page tree – see Caching.

Default: true (Kirby's default cache driver)

ai.systemPrompt String

When using AI translation, you can replace the built-in system prompt with a custom one. Set it globally or override it per blueprint.

Default: none (the built-in system prompt)

return [
    'johannschopplich.content-translator' => [
        'ai' => [
            'systemPrompt' => 'You are a medical translator. Preserve clinical terminology and abbreviations.'
        ]
    ]
];