README

This Kirby plugin allows you to automatically translate pages using the DeepL API. All field types are supported.

If you are using machine translation, you should inform your users of this fact.
For example, you could display a message like this (Text available via t('tobiaswolf.machine-translation.info'))

This page has been machine translated. Despite the high quality of machine translation, the translation may contain errors.

Installation

Download

Download and copy this repository to /site/plugins/machine-translation.

Git submodule

git submodule add https://github.com/tobiasfabian/machine-translation.git site/plugins/machine-translation

Composer

composer require tobiasfabian/machine-translation

Requirements

• Kirby 5.0+
• Authentication Key for DeepL API (DeepL API for developers)

Setup

To use this plugin you have to set your personal Authentication Key for DeepL API. API Access / Authentication – DeepL Documentation

// config/config.php
return [
  'tobiaswolf.machine-translation.deepl.authKey' => '279a2e9d-83b3-c416-7e2d-f721593e42a0:fx',
];

DeepL Options

You can set several options, provided by DeepL. Read more about the options in the API Documentation of DeepL. Each option has to be prefixed. tobiaswolf.machine-translation.deepl.{Name}

Usage

Blueprint section

Add the section machine-translate to your blueprint to get the interface to translate the page.

sections:
  machineTranslate:
    type: machine-translate

After the page is translated an object field machineTranslated with date and showInfo is saved to the translated page content. This can be used to detect machine translated pages and display a notice/warning on the frontend that the text is machine translated. You can add this object field to any fields section (optional).

sections:
  fields:
    type: fields
    fields:
      machineTranslated:
        extends: fields/machineTranslated

API endpoint

This plugin provides an API endpoint /api/machine-translate/pages/(:any) that can be used to translate an entire page. Read Kirby’s API Guide to learn more about using the API.

The endpoint allows get and post requests. The endpoint requires a language (target language) query. When making a post request, sourceLang and forceOverwrite can be added. By default sourceLang is the default language. If forceOverwrite is false or not specified, only fields where the target field does not exist or is empty will be translated.

const pageId = 'test';
const targetLang = 'es';
const csrf = '…';
fetch(`/api/machine-translate/pages/{ pageId }?language={ targetLang }`, {
	method: 'post',
	body: JSON.stringify({
		sourceLang: 'en',
		forceOverwrite: true,
	}),
	headers: {
		'x-csrf': csrf,
	},
});

$pageId = 'test';

kirby()->api()->call('machine-translate/pages/' . $pageId, 'POST', [
	'query' => [
		'language' => 'en',
	],
	'body' => [
		'sourceLang' => 'de',
		'forceOverwrite' => true,
	],
]);

API endpoint to translate the site content. /api/machine-translate/site

Field method

The field method $field->translate($targetLang, $blueprintField) translates the field value and returns the field with the translated value. All field types are supported. The type of field is specified via $blueprintField['type'].

If you want to save the translated field, you can do this like this.

$targetLang = 'de'
$text = $page->text(); // e.g. Hello World
$translatedText = $text->translate($targetLang); // returns the field with the translated text (Hallo Welt)
$page->update([
  'text' => $translatedText,
], $targetLang);

Page method

The page method $page->machineTranslate($targetLang, $sourceLang, $force) allows you to translate the content of a page into a target language. By default already translated fields will not be overwritten. By setting $force to true all fields will be translated, existing fields will be overwritten.

An object field machineTranslated with date and showInfo is added to the translated page content. This can be used to detect machine translated pages and display a notice/warning on the frontend that the text is machine translated.

To translate the site content, use $site->machineTranslate($targetLang, $sourceLang, $force).

Translate Class

If you want to, you can use the static method of the Translate class. Use the translate($text, $targetLang, $sourceLang) method to translate text. Make sure you pass an array as the first parameter (you can translate multiple texts at once). You can omit the third parameter to have the source language automatically detected.

use Tobiaswolf\MachineTranslation\Translate;

$sourceTexts = ['Hello World', 'Greetings Earthlings'];
$translatedTexts = Translate::translate($sourceTexts, 'es');

var_dump($translatedTexts);
// array(2) { [0]=> array(2) { ["detected_source_language"]=> string(2) "EN" ["text"]=> string(10) "Hola Mundo" } [1]=> array(2) { ["detected_source_language"]=> string(2) "EN" ["text"]=> string(19) "Saludos terrícolas" } }

Cache

Each request to DeepL is cached. This has the advantage that if the same text appears more than once on the website, a new request is not always made. This saves you Character usage of your DeepL plan.

You can disable the cache via config.

// config/config.php
return [
	'cache.tobiaswolf.machine-translation.translate' => false, // default true
]

License

MIT

Credits

• Tobias Wolf