Configuration

The Kirby Content Translator empowers editors to copy content from one language to another and translate content of fields. This page describes all the available configuration options for the Content Translator section to help you set up the plugin according to your needs.

Section Properties

label String

The label property allows you to define a custom label for the Content Translator section. The default value depends on the language of the Panel. For English, the default label is Content Translator.

To set a custom label for the plugin section, use the label property in your blueprint:

type: content-translator
label: Translation Helper

fieldTypes Array

This is one of the core section properties. By default, the plugin imports or translates all text-like fields: list, text, textarea, and writer. These fields can be nested in blocks, layout, object, and structure fields.

If you want to limit the translation to specific field types, you can use the fieldTypes property. The following field types are supported (and enabled by default):

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

To only translate text and textarea fields, use the following configuration:

type: content-translator
fieldTypes:
  - text
  - textarea

However, text fields inside blocks for example will not be imported or translated with this configuration, because the blocks field type is not included. To translate fields within blocks, you need to add the blocks field type to the fieldTypes array:

type: content-translator
fieldTypes:
  - blocks
  - text
  - textarea

includeFields Array

The includeFields property allows you to specify a list of fields that should be imported or translated. This property is useful if you want to translate only specific fields, either nested or not. The fieldTypes property is still respected.

To translate only the company and author fields, use the following configuration:

type: content-translator
includeFields:
  - company
  - author

excludeFields Array

Similar to the includeFields property, the excludeFields property allows you to specify a list of fields that should not be imported or translated. This property is useful if you want to exclude specific fields from the translation process when excluding a field type is not sufficient.

To exclude the description and summary fields from the translation, use the following configuration:

type: content-translator
excludeFields:
  - description
  - summary

import Boolean

If the importing of content to any page should be disabled, you can set the import property to false. This will hide the import button in the section.

type: content-translator
import: false

With the disabled import feature (and bulk feature for the sake if the screenshot), the section will look like this for a secondary language:

importFrom String

With the default plugin configuration, the import process will only allow copying content from the default language to secondary languages. Not the other way around. This protects the content of the default language from being overwritten. That's why in the default language only the → All Languages button is rendered:

(If you have disabled the bulk translation feature, the Panel section will indicate that importing from secondary languages is disabled:)

To allow overwriting content of the default language by importing from a secondary language, you can set the importFrom property to all. This will enable you to import content from the secondary language to the default language:

type: content-translator
importFrom: all

The button text will change slightly to indicate that importing from secondary languages is allowed:

bulk Boolean

Kirby Content Translator v2.3.0+ allows you to translate the content of a given site, page or file model into all secondary languages in bulk. This means that you can now not only translate content per language, but also for all secondary languages at once: the content of all secondary languages is overwritten with the data of the default language and then translated into the respective language.

This option is only active for the default language:

The button is only enabled when the default language content is active in the Panel. When the button is clicked, a confirmation dialog is displayed to prevent accidental bulk translation:

For security reasons, the confirmation modal cannot be disabled with the confirm property.

If you want to disable bulk translation for multiple languages at once, you can set the bulk property to false. This will hide the bulk translation button in the section:

type: content-translator
bulk: false

title Boolean

You can enable to import and translate the title of a model by setting the title section property to true:

type: content-translator
title: true

slug Boolean

Similar to the title property, you can enable to import and translate the slug of a model by setting the slug section property to true. This will change the slug of the model to the slugified translation of the translated title.

type: content-translator
slug: true

confirm Boolean

To make sure an editor does not accidentally import or translate content and thus overwrite existing translations, a confirmation dialog is displayed before the process is started. If you want to skip this dialog, you can set the confirm key to false:

type: content-translator
confirm: false

Global Configuration

Instead of defining the configuration in every blueprint, you can also define global defaults in your config file. This is especially useful if, for example, every page's blocks should be translated the same way.

return [
    'johannschopplich.content-translator' => [
        'fieldTypes' => [
            'blocks',
            'text',
            'textarea'
        ],
        'title' => true,
        'slug' => true,
        'confirm' => false
    ]
]

Custom Translator Function

Instead of using the DeepL API, you can define a custom translator callback that accepts the text to be translated, the source language code and the target language code. The plugin expects a string to be returned.

return [
    'johannschopplich.content-translator' => [
        'translateFn' => function (string $text, string $toLanguageCode, string|null $fromLanguageCode = null): string {
            // Your custom translation logic
            return myCustomTranslateFunction($text, $toLanguageCode, $fromLanguageCode);
        }
    ]
];

Mapping Language Codes

In certain cases, a language code defined in Kirby might not match the language code expected by the translation service. You can map language codes in the custom translator function:

return [
    'johannschopplich.content-translator' => [
        'translateFn' => function (string $text, string $toLanguageCode, string|null $fromLanguageCode = null): string {
            // Map `cz` to `cs` for DeepL
            if ($targetLanguage === 'cz') {
                $targetLanguage = 'cs';
            }

            $deepL = new DeepL();
            return $deepL->translate($text, $targetLanguage, $sourceLanguage);
        }
    ]
];

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