Kirby Tools
v3.11.2Hub

Migration

Upgrade notes for breaking and notable changes – strategy interface, view-button defaults, HTML tag handling.

Migrating to v3.11 (Strategy Refactor)

v3.11 introduces a typed Strategy interface and a unified strategy config option. No breaking changes – existing code keeps working unchanged. Two deprecations to watch for v4:

  • johannschopplich.content-translator.translateFn – migrate to 'strategy' => $closure. Signature is identical.
  • JohannSchopplich\ContentTranslator\KirbyText::translateText() – migrate to Translator::translateText(). Same routing, same result.

translateFn → strategy

config.php
 return [
     'johannschopplich.content-translator' => [
-        'translateFn' => function (string $text, string $target, ?string $source) { /* … */ },
+        'strategy' => function (string $text, string $target, ?string $source) { /* … */ },
     ],
 ];

When both keys are set, strategy wins.

KirbyText::translateText() → Translator::translateText()

-use JohannSchopplich\ContentTranslator\KirbyText;
-$translated = KirbyText::translateText($text, 'de', 'en', $kirbyTags);
+use JohannSchopplich\ContentTranslator\Translator;
+$translated = Translator::translateText($text, 'de', 'en');

The new pipeline routes through the configured strategy and handles KirbyTags structurally without per-call configuration.

For the new architecture, see PHP Classes → Strategies.

Migrating From v2 to v3

Kirby Content Translator v3 is a major overhaul in terms of architecture and features. No breaking changes have been introduced in this version. However, if you are using Kirby 4, you might want to disable the Panel view button, which is now enabled by default.

In Kirby 4, Panel view buttons are not supported. But the feature has been backported. The content-translator button is always placed after the language dropdown and cannot be moved. If you want to disable the button, set the viewButton option to false:

config.php
return [
    'johannschopplich.content-translator' => [
        'viewButton' => false
    ]
]

In Kirby 5, you can enable the Content Translator view buttons per blueprint. The following example shows how to reference the default buttons and add the content-translator button to the site, pages, and files views:

buttons:
  - open
  - preview
  - content-translator # Re-order the button as needed
  - languages

Migrating From v2.x to v2.5

Some users experienced issues with fields where the field content is HTML (e.g. in a writer field). With Kirby Content Translator v2.5, every request to the DeepL API is now sent with the tag_handling parameter set to html. This should fix the issue with HTML content not being translated correctly.

If you experience problems with this new default, you can disable it by setting the tag_handling option to null in the global configuration:

config.php
return [
    'johannschopplich.content-translator' => [
        'DeepL' => [
            'requestOptions' => [
                // Disable the `tag_handling` parameter
                'tag_handling' => null
            ]
        ]
    ]
];

Installation

Set up DeepL or AI-powered translation, choose your Panel workflow, and start translating content in minutes.

Global Configuration

Set the translation backend, credentials, and project-wide defaults in config.php – applies to every view button and section.