Kirby Tools
v3.11.0Hub

Translator

Translate any page, file, or site model in place from PHP – with static helpers when you only have raw strings.

Build a Translator for any page, file, or site to copy and translate content from PHP. Mutate the model in place, then read the updated state back via model().

use JohannSchopplich\ContentTranslator\Translator;

$translator = new Translator(page('blog/article'));
$translator->copyContent('de', 'en');
$translator->translateContent('de', 'de', 'en');

$page = $translator->model();
The same instance is exposed as a model method on Site, Page, and File: $page->translator(). The translator() global helper mirrors the constructor.

Construction

public function __construct(Site|Page|File $model, array $options = [])
model
Site | Page | File
The Kirby model whose content you want to translate.
options
Array
Per-instance overrides for the same scoping options as the global config – fieldTypes, includeFields, excludeFields, kirbyTags.
$translator = translator(page('blog/article'), [
    'fieldTypes' => ['text', 'textarea', 'blocks'],
    'excludeFields' => ['date', 'author'],
]);

Instance Methods

copyContent

Copy a source language's content over to a target language. Overwrites the target.

public function copyContent(string $toLanguageCode, string $fromLanguageCode): void

$translator->copyContent('de', 'en'); // Copy English → German
When you copy from the default language to a secondary language on Kirby 5+, the target content file is deleted instead of overwritten – Kirby's built-in language inheritance keeps it in sync until you actually translate it.

translateContent

Translate the content already stored in $contentLanguageCode and save it back. The fourth parameter overrides the configured strategy for this call only.

public function translateContent(
    string $contentLanguageCode,
    string $toLanguageCode,
    string|null $fromLanguageCode = null,
    Strategy|null $strategy = null,
): void

Typical pattern – copy first, then translate the duplicated content:

$translator->copyContent('de', 'en');
$translator->translateContent('de', 'de', 'en');
Throws TranslationException when the strategy fails for every collected unit. See Exceptions.

translateTitle

public function translateTitle(
    string $contentLanguageCode,
    string $toLanguageCode,
    string|null $fromLanguageCode = null,
): void

Translate the model title. Falls back to the source language when the target-language title is empty.

$translator->translateTitle('de', 'de', 'en');

translateSlug

public function translateSlug(
    string $contentLanguageCode,
    string $toLanguageCode,
    string|null $fromLanguageCode = null,
): void

Rename the page slug from the translated title. No-op for the homepage, the error page, and non-page models.

$translator->translateSlug('de', 'de', 'en');

model

public function model(): Site|Page|File

Mutating methods don't return the new model. Reach for model() to grab the up-to-date instance:

$translator->translateContent('de', 'de');

// $page still holds the pre-translation model
echo $page->content()->get('text');

// Reassign to read the translation
$page = $translator->model();
echo $page->content()->get('text');

Static Helpers

Translate raw strings without a model. Both methods return the source unchanged for empty strings, pure numbers, and standalone URLs.

public static function translateText(
    string $text,
    string $targetLanguage,
    string|null $sourceLanguage = null,
    Strategy|null $strategy = null,
): string

public static function translateTexts(
    array $texts,
    string $targetLanguage,
    string|null $sourceLanguage = null,
    Strategy|null $strategy = null,
): array

Prefer translateTexts() over a loop – DeepL packs up to 50 texts per request, and the AI strategy chunks intelligently.

echo Translator::translateText('Hello world', 'de', 'en');
// "Hallo Welt"

$translated = Translator::translateTexts(['Hello', 'Goodbye'], 'de', 'en');
// ['Hallo', 'Auf Wiedersehen']

The optional $strategy parameter on translateText, translateTexts, and translateContent overrides the configured strategy for one call:

use JohannSchopplich\ContentTranslator\Translation\Strategies\CopilotAIStrategy;

Translator::translateText('Hello', 'de', 'en', new CopilotAIStrategy());

See Strategies for the full interface and built-in implementations.

Overview

Translate Kirby pages, files, and site content from PHP – the same pipeline the Panel uses, exposed as a public API.

Overview

Pluggable translation backends – pick DeepL, Copilot AI, or a callable, or implement your own to route through any service.