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, the section will look like this:

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. The Panel section will indicate that importing from secondary languages is disabled:

If you want 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:

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);
        }
    ]
];