Global Configuration

Configure translation providers, API keys, and global defaults.

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:

config.php
return [
    'johannschopplich.content-translator' => [
        'DeepL' => [
            'apiKey' => '<deepl-api-key>',
        ]
    ]
]
The plugin will automatically use the free or pro API endpoint based on your API key.

Custom Translation Function

Follow the dedicated Custom Translation Function guide for more details.

For advanced use cases, you can provide a custom translation function:

config.php
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:

config.php
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:

config.php
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:

config.php
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:

Blueprint Override
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.

See the plugin's 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:

languages/en.php
return [
    'code' => 'en',
    'name' => 'English',
    // ... Other language configuration
    'translations' => [
        'johannschopplich.content-translator.import' => 'Synchronize'
    ]
];

Panel View Button (Kirby 4 Only)

In Kirby 5, view buttons are configured directly in blueprints. See the View Button & Section Configuration page.

Kirby Content Translator Panel view button

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:

config.php
return [
    'johannschopplich.content-translator' => [
        'viewButton' => false // Disable the view button globally
    ]
]