johannschopplich / kirby-content-translator
Kirby Panel plugin to translate content at once with DeepL or other services
Fund package maintenance!
paypal.me/jschopplich
Installs: 958
Dependents: 0
Suggesters: 0
Security: 0
Stars: 30
Watchers: 2
Forks: 2
Open Issues: 0
Type:kirby-plugin
Requires
Requires (Dev)
- friendsofphp/php-cs-fixer: @stable
- getkirby/cms: ^4
README
Kirby Content Translator
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:
- Synchronise content from the default language to the secondary language.
- Translate content using the DeepL API or a custom translation service.
Key Features
- 🚌 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
Preview
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.
Requirements
- Kirby 4+
Kirby is not free software. However, you can try Kirby and the Starterkit on your local machine or on a test server as long as you need to make sure it is the right tool for your next project. … and when you’re convinced, buy your license.
Installation
Composer
composer require johannschopplich/kirby-content-translator
Download
Download and copy this repository to /site/plugins/kirby-content-translator
.
Getting Started
DeepL Account
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.
Panel Section
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
Tip
By default, all built-in Kirby blocks that include a text-like field are pre-configured to be translated. You can override this behaviour by defining your own translatableBlocks
configuration.
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…' ] ] ];
Configuration
The following blueprint configuration options are available for the content-translator
Panel section:
Key | Type | Default | Description |
---|---|---|---|
syncableFields |
Array | [] |
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. |
translatableFields |
Array | [] |
The fields that should be translated when the user clicks the translate button. |
translatableStructureFields |
Array | [] |
The fields inside sections that should be translated. For the section field itself, add its field key to the translatableFields array. |
translatableBlocks |
Array | See sections.php |
The block names and their corresponding fields that should be translated when the user clicks the translate button. By default, all Kirby blocks that include a text-like field are translated. |
title |
Boolean | false |
Whether the title of the model should be synchronised and translated. |
label |
String or Array | See translations.php |
Optionally, you can translate the section label. |
confirm |
Boolean | true |
Disable the confirmation dialog before either the synchronisation or translation process is started. |
Tip
If no syncableFields
are defined, the button to synchronise content will not be displayed.
Translatable Blocks
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
Note
The blocks configuration for built-in Kirby blocks is defined in sections.php
.
Translatable Structure Fields
The plugin translates fields within structures. The structures may be part of the current model or a block. For example, if you have a structure
field with a text
field inside, you can translate the text
field by first adding it to the translatableStructureFields
array:
translatableStructureFields: - text
Then, depending on whether the structure
field is part of the current model or a block, you need to add the key of the structure
field to the translatableFields
or translatableBlocks
array:
# When your structure is part of the current model: translatableFields: - myStructure # Or else, if your structure is part of a block: translatableBlocks: myBlockWithStructure: - structureInBlock
Translating the Title
You can enable to synchronise and translate the title of a model by setting the title
section property to true
:
sections: contentTranslator: type: content-translator title: true
Important
Technically speaking, the title is not part of the content of a Kirby model. That's why you can't revert changes made to the title, as opposed to fields. Also, when synchronising content, the title will be overwritten. Because of these caveats, have to opt-in to synchronise and translate the title.
Section Label
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
Skip Dialogs Before Synchronising/Translating
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
Global Configuration Defaults
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.
Note
Local blueprint configurations will always override global defaults.
# /site/config/config.php return [ 'johannschopplich.content-translator' => [ 'syncableFields' => ['text', 'description'], 'translatableFields' => ['text', 'description'], 'translatableBlocks' => [ 'heading' => ['text'], 'text' => ['text'], 'image' => ['alt', 'caption'] ], 'confirm' => false ] ]
Allow Overwriting Content of the Default Language
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 ] ]
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.
# /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); } ] ];
License
MIT License © 2023-PRESENT Johann Schopplich
MIT License © 2023-PRESENT Dennis Baum