PHPackages tobiaswolf/machine-translation - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. tobiaswolf/machine-translation ActiveKirby-plugin tobiaswolf/machine-translation ============================== Translate pages/fields with Deepl API 1.0.0-beta.4(2y ago)61[1 issues](https://github.com/tobiasfabian/kirby-machine-translation/issues)MITPHP Since Jul 27Pushed 1y ago2 watchersCompare [ Source](https://github.com/tobiasfabian/kirby-machine-translation)[ Packagist](https://packagist.org/packages/tobiaswolf/machine-translation)[ GitHub Sponsors](https://github.com/tobiasfabian)[ RSS](/packages/tobiaswolf-machine-translation/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (1)Versions (4)Used By (0) Machine Translation =================== [](#machine-translation) 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')`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/translations/en.php#L17)) ``` This page has been machine translated. Despite the high quality of machine translation, the translation may contain errors. ``` Installation ------------ [](#installation) ### Download [](#download) Download and copy this repository to `/site/plugins/machine-translation`. ### Git submodule [](#git-submodule) ``` git submodule add https://github.com/tobiasfabian/machine-translation.git site/plugins/machine-translation ``` ### Composer [](#composer) ``` composer require tobiasfabian/machine-translation ``` Requirements ------------ [](#requirements) - Kirby 4.0+ - Authentication Key for DeepL API ([DeepL API for developers](https://www.deepl.com/de/pro#developer)) Setup ----- [](#setup) To use this plugin you have to set your personal *Authentication Key for DeepL API*. [API Access / Authentication – DeepL Documentation](https://www.deepl.com/docs-api/api-access/authentication/) ``` // config/config.php return [ 'tobiaswolf.machine-translation.deepl.authKey' => '279a2e9d-83b3-c416-7e2d-f721593e42a0:fx', ]; ``` ### DeepL Options [](#deepl-options) You can set several options, provided by DeepL. Read more about the options in the [API Documentation](https://www.deepl.com/docs-api/translate-text/translate-text/) of DeepL. Each option has to be prefixed. `tobiaswolf.machine-translation.deepl.{Name}` NameTypeDefaultDescription`authKey` **(required)**`string``null`You can find your Auth key on your account page. [DeepL Documentation](https://www.deepl.com/docs-api/api-access/authentication/)`split_sentences``string``nonewlines`Possible values are: `0` no splitting at all, whole input is treated as one sentence. `1` splits on punctuation and on newlines. `nonewlines` splits on punctuation only, ignoring newlines`preserve_formatting``bool``false`Sets whether the translation engine should respect the original formatting, even if it would usually correct some aspects.`formality``string``default`You can use one of these options: `default` (default), `more` for a more formal language, `less` for a more informal language, `prefer_more` for a more formal language if available, otherwise fallback to default formality, `prefer_less` for a more informal language if available, otherwise fallback to default formality.`glossary_id``string``null`Specify the glossary to use for the translation. The language pair of the glossary has to match the language pair of the request.`tag_handling``string``html`Sets which kind of tags should be handled. Options currently available: `xml`, `html``outline_detection``bool``true` [API Documentation](https://www.deepl.com/docs-api/translate-text/translate-text/)`non_splitting_tags``array``null`List of XML or HTML tags.`splitting_tags``array``null`List of XML or HTML tags.`ignore_tags``array``null`List of XML or HTML tags.Usage ----- [](#usage) ### Blueprint section [](#blueprint-section) Add the section [`machine-translate`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/sections/machineTranslate.php) to your blueprint to get the interface to translate the page. ``` sections: machineTranslate: type: machine-translate ``` [![Screenshot of Kirby Panel with Button “Translate page”](https://private-user-images.githubusercontent.com/1524319/256535227-f85d94a1-0cb7-4b8c-9ed1-9a4a0a93f98c.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU1NjAzNzUsIm5iZiI6MTc3NTU2MDA3NSwicGF0aCI6Ii8xNTI0MzE5LzI1NjUzNTIyNy1mODVkOTRhMS0wY2I3LTRiOGMtOWVkMS05YTRhMGE5M2Y5OGMucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwNyUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDdUMTEwNzU1WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZmEyZGMzYjdiN2RlOTZjNDM0ZTAzMGY2ZWZkZjhmNjNjM2IwM2IwOTI2ZDliY2I1ZWViYzZlYWVjMzUyYmZjYyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.TXtb_bimIgX5fHFp1Mo6IKjwe7JIikzeDuOoDXw33sc)](https://private-user-images.githubusercontent.com/1524319/256535227-f85d94a1-0cb7-4b8c-9ed1-9a4a0a93f98c.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU1NjAzNzUsIm5iZiI6MTc3NTU2MDA3NSwicGF0aCI6Ii8xNTI0MzE5LzI1NjUzNTIyNy1mODVkOTRhMS0wY2I3LTRiOGMtOWVkMS05YTRhMGE5M2Y5OGMucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwNyUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDdUMTEwNzU1WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ZmEyZGMzYjdiN2RlOTZjNDM0ZTAzMGY2ZWZkZjhmNjNjM2IwM2IwOTI2ZDliY2I1ZWViYzZlYWVjMzUyYmZjYyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.TXtb_bimIgX5fHFp1Mo6IKjwe7JIikzeDuOoDXw33sc)After the page is translated an object field [`machineTranslated`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/blueprints/fields/machineTranslated.yml) 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 [](#api-endpoint) This plugin provides an API endpoint [`/api/machine-translate/pages/(:any)`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/api/routes/machine-translate.php#L10-L41) that can be used to translate an entire page. Read [Kirby’s API Guide](https://getkirby.com/docs/guide/api/introduction) 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`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/api/routes/machine-translate.php#L42-L73) ### Field method [](#field-method) The field method [`$field->translate($targetLang, $blueprintField)`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/field-methods/translate.php) 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 [](#page-method) The page method [`$page->machineTranslate($targetLang, $sourceLang, $force)`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/page-methods/machineTranslate.php) 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)`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/site-methods/machineTranslate.php). ### Translate Class [](#translate-class) If you want to, you can use the static method of the [`Translate`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/lib/Translate.php) class. Use the [`translate($text, $targetLang, $sourceLang)`](https://github.com/tobiasfabian/kirby-machine-translation/blob/main/lib/Translate.php#L201) 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 [](#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 ------- [](#license) MIT Credits ------- [](#credits) - [Tobias Wolf](https://github.com/tobiasfabian) ### Health Score 21 — LowBetter than 18% of packages Maintenance32 Infrequent updates — may be unmaintained Popularity6 Limited adoption so far Community8 Small or concentrated contributor base Maturity32 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~4 days Total 3 Last Release 1018d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7fbee332d82aa554b6740f3565e88c3bc2b8908d16887fcbc924808f1e9c7e43?d=identicon)[tobiasfabian](/maintainers/tobiasfabian) --- Top Contributors [![tobiasfabian](https://avatars.githubusercontent.com/u/1524319?v=4)](https://github.com/tobiasfabian "tobiasfabian (15 commits)") --- Tags deeplkirby-4kirby-plugin ### Embed Badge ![Health badge](/badges/tobiaswolf-machine-translation/health.svg) ``` [![Health](https://phpackages.com/badges/tobiaswolf-machine-translation/health.svg)](https://phpackages.com/packages/tobiaswolf-machine-translation) ``` ### Alternatives [getkirby/cms The Kirby core 1.5k535.5k352](/packages/getkirby-cms)[distantnative/retour-for-kirby Manage redirects and track 404s right from the Kirby CMS Panel 14689.4k1](/packages/distantnative-retour-for-kirby)[arnoson/kirby-vite Vite helper for Kirby CMS 9759.2k3](/packages/arnoson-kirby-vite)[getkirby/staticache Static site performance on demand 9615.4k](/packages/getkirby-staticache)[fabianmichael/kirby-meta Your all-in-one powerhouse for any SEO and metadata needs imaginable. 6910.7k1](/packages/fabianmichael-kirby-meta)[thathoff/kirby-oauth Kirby OAuth 2 Plugin 3823.9k](/packages/thathoff-kirby-oauth) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)