Sometimes you may find yourself copying content from Kirby fields to your clipboard, only to paste it into a translation service of your choice. This plugin aims to simplify the translation process by providing a simple interface for translating a model's content (page, file, etc.), while allowing full flexibility in choosing which fields to translate.

With a single click, an editor can:

1. Synchronise content from the default language to the secondary language.
2. Translate content using the DeepL API or a custom translation service.

• 🚌 Supports writer, blocks, layouts and other Kirby fields
• 🧮 Configure which fields should be translated
• 🌐 Translate all fields with one click
• 🌝 Panel buttons
• 🧩 Use DeepL API or custom translation service

For the following preview, I used the example section blueprint to synchronise the description and text fields, which are of type writer and blocks, respectively.

The default language in the example is English. The secondary language is German, to which the content is first synchronised (copied) and then translated.

• Kirby 4+

Kirby is not a free software. You can try it for free on your local machine but in order to run Kirby on a public server you must purchase a valid license.

composer require johannschopplich/kirby-content-translator

Download and copy this repository to /site/plugins/kirby-content-translator.

By default, this plugin uses the DeepL API to translate your content. You can use any other translation service by defining a custom translator function (see below).

In order to use the DeepL API, you have to create an account and generate an API key.

First, set up the Panel section in one of your blueprints, e.g. a page blueprint and configure the fields that should be synchronised and translated:

• The syncableFields key defines the fields that should be copied from the default language to the secondary language when the user is editing content in any language but the default language and clicks the synchronise button.
• The translatableFields key defines the fields that should be translated when the user clicks the translate button.

Below is an example configuration with common configuration options:

sections:
  contentTranslator:
    type: content-translator
    # Define field names which should be synced from the default language to other languages
    syncableFields:
      - text
      - description
      - tags
    # Define field names that should be translated
    translatableFields:
      - text
      - description

Finally, store the DeepL API key in your config file:

# /site/config/config.php
return [
    'johannschopplich.content-translator' => [
        // API key for the DeepL free or pro plan
        'DeepL' => [
            'apiKey' => 'abc123…'
        ]
    ]
];

The following blueprint configuration options are available for the content-translator Panel section:

If you create custom Kirby blocks, you probably want to translate their content as well. To do so, you can define the block names and their corresponding fields that should be translated when the user clicks the translate button:

sections:
  contentTranslator:
    type: content-translator
    # Given the `text` field is of type `blocks`
    translatableFields:
      - text
    # Define the field names inside blocks which should be translated
    translatableBlocks:
      # Example: translate the `alt` and `caption` fields of the `myImage` block
      myImage:
        - alt
        - caption
      # Example: translate the `caption` field of the `myGridCard` block
      myGridCard:
        - caption

Optionally, you can translate the section label by adding a label key:

sections:
  contentTranslator:
    type: content-translator
    # Either use a single label for all languages
    label: Translator
    # Or use language codes for multilingual labels
    # label:
    #   en: Translator
    #   de: Übersetzer

To make sure an editor doesn't accidentally synchronise 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:

sections:
  contentTranslator:
    type: content-translator
    confirm: false

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.

# /site/config/config.php
return [
    'johannschopplich.content-translator' => [
        'syncableFields' => ['text', 'description'],
        'translatableFields' => ['text', 'description'],
        'translatableBlocks' => [
            'heading' => ['text'],
            'text' => ['text'],
            'image' => ['alt', 'caption']
        ],
        'confirm' => false
    ]
]

With the default plugin configuration, the synchronisation process will only copy content from the default language to secondary languages. If you want to allow overwriting content of the default language, you can set the allowOverwrite key to true. This will enable you to synchronise content from the secondary language to the default language.

# /site/config/config.php
return [
    'johannschopplich.content-translator' => [
        'allowDefaultLanguageOverwrite' => true
    ]
]

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.

# /site/config/config.php
return [
    'johannschopplich.content-translator' => [
        'translateFn' => function (string $text, string|null $sourceLanguageCode, string $targetLanguageCode): string {
            // Your custom translation logic
            return myCustomTranslateFunction($text, $sourceLanguageCode, $targetLanguageCode);
        }
    ]
];

MIT License © 2023-PRESENT Johann Schopplich

MIT License © 2023-PRESENT Dennis Baum