PHP API

Programmatically translate content using PHP methods for automation and CLI commands.

The Content Translator PHP API provides powerful methods to copy and translate content programmatically. This is perfect for automation, CLI commands, or custom workflows.

Global Functions

Kirby Content Translator provides two global functions to simplify the usage of the PHP API. Call them from anywhere in your project.

The translator() function creates a new instance of the Translator class. It accepts a Kirby Site, Page, or File model as the first argument and an optional array of options as the second argument.

$page = page('example');
$translator = translator($page);

Type Definitions

function translator(Site|Page|File $model, array $options = []): \JohannSchopplich\ContentTranslator\Translator

`translate()`

The translate() function translates a given text from a source language to a target language. It accepts the text to translate as the first argument, the target language as the second argument, and the source language as the third argument. The source language is optional.

echo translate('Hello', 'de');

Passing the source language as the third argument can improve the translation quality, since DeepL does not always detect the source language correctly (especially for short texts). If you know the source language, you can provide it to get better results:

echo translate('Hello', 'de', 'en');

Be aware that translations are not cached. If you need to translate the same text multiple times, it is recommended to cache the results.

Type Definitions

function translate(string $text, string $targetLanguage, string|null $sourceLanguage = null): string

Model Methods

You can initialize a new Translator instance directly on a Site, Page, or File model, instead of using the global translator() function:

$site = site();
$translator = $site->translator();

$page = page('example');
$translator = $page->translator();

$file = $page->files()->first();
$translator = $file->translator();

`Translator` Class Methods

The JohannSchopplich\ContentTranslator\Translator class provides a set of methods to copy and translate content programmatically.

`copyContent`

The copyContent() method copies the content of the source language to the content of the target language. This will overwrite the content of the target language.

$page = page('example');
$translator = $page->translator();
// Copy the default language (English) content to the secondary language (German)
$translator->copyContent('de', 'en');

Type Definitions

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

`translateContent`

The translateContent() method translates the content from the source language to the target language. Note that the source language is optional.

Say you have already copied the content from the default language to a secondary language and now want to translate the content of the secondary language, which is still just a copy of the default language:

$page = page('example');
$translator = $page->translator();

// Copy the default language (English) content to the secondary language (German)
$translator->copyContent('de', 'en');

// Translate the copied content to German, because the content is still in English
$translator->translateContent(
    // This is the language of the content that should be translated
    'de',
    // This is the target language
    'de'
);

Type Definitions

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

`translateTitle`

The translateTitle() method translates the title of a page. The source language is optional.

$page = page('example');
$translator = $page->translator();
// Translate the title of the German content to English
$translator->translateTitle('de', 'en');

Type Definitions

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

`translateSlug`

The translateSlug() method renames the slug of a page based on the translated title.

If the selected model is the homepage, this method will skip the translation and return early.

$page = page('example');
$translator = $page->translator();
// Rename the slug of the German content based on translated title
$translator->translateSlug('de', 'en');

Type Definitions

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

`model`

When making changes to a model's content, Kirby returns a clone of the model. To get the updated model with translated content, use the model() method:

$page = page('example');
$translator = $page->translator();

// Translate the content
$translator->translateContent('de', 'de');

// Now, the `$page` model still contains the untranslated content…
echo $page->content()->get('text'); // Outputs the untranslated text

// Reassign the model to get the updated content
$page = $translator->model();

// Now, the `$page` model contains the translated content
echo $page->content()->get('text'); // Outputs the translated text

Type Definitions

public function model(): Site|Page|File

Configuration

You can configure the PHP API similarly to the Panel configuration. The following configuration options are available:

fieldTypes - Which field types to translate
includeFields - Specific fields to include
excludeFields - Specific fields to exclude

Pass the configuration as the second argument when creating a translator:

$translator = translator(page('example'), [
    'fieldTypes' => ['text', 'textarea'],
    'excludeFields' => ['company']
]);

// Or when using model methods
$page = page('example');
$translator = $page->translator([
    'fieldTypes' => ['text', 'textarea'],
    'includeFields' => ['title', 'description']
]);

Complete Example

Here's a complete example that copies and translates a page:

// Get the page to translate
$page = page('blog/my-article');

// Create translator with custom configuration
$translator = $page->translator([
    'fieldTypes' => ['text', 'textarea', 'blocks'],
    'excludeFields' => ['date', 'author']
]);

// Copy content from English to German
$translator->copyContent('de', 'en');

// Translate the copied content
$translator->translateContent('de', 'de', 'en');

// Also translate the title
$translator->translateTitle('de', 'de', 'en');

// Get the updated page model
$page = $translator->model();

echo "Translated page: " . $page->title()->value();

Hooks

Use the Content Translator plugin hooks to customize translation behavior.

Basic Usage Examples

Common scenarios and workflows for using the Content Translator plugin.