Migration

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:

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

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

Migrating from v1 to v2

The Kirby Content Translator v2 is a major overhaul in terms of architecture and features. This guide will help you migrate your existing projects from the v1 version of the plugin to the v2 version.

New Configuration Options

While the v1 version relied on parameters like syncableFields, translatableFields, translatableStructureFields, etc., the v2 version introduces a more streamlined approach to managing translatable content. The new version uses a single fieldTypes property to define the fields types that should be translated.

By default, the following field types are supported and enabled:

• blocks
• layout
• list
• object
• structure
• tags
• text
• textarea
• writer
• markdown

If you want to limit the translation to specific field types, you can use the fieldTypes property.

To include or exclude specific fields, you can use the includeFields and excludeFields properties. Both are empty by default. Note that if at least one entry is defined in includeFields, only these fields will be translated. Respectively, if at least one entry is defined in excludeFields, all fields except these will be translated.

For example, if you want to translate your whole content, except the company field name, you can use the following configuration:

type: content-translator
excludeFields:
  - description
  - summary

Removed Properties

The following section properties have been removed in the v2 version in favor of the new fieldTypes, includeFields, and excludeFields properties:

• syncableFields
• translatableFields
• translatableStructureFields
• translatableObjectFields
• translatableBlocks

PHP API

Since the PHP API is new in the v2 version, there is no need to migrate any existing PHP code.