PHP API

Giving editors the power to copy and translate content is a great. But for certain use cases, you might want to automate this process. This is where the PHP API comes into play. The plugin provides a set of methods and global functions to copy and translate content programmatically.

For example, you can write a CLI command to translate all pages for a new language that was just added to your project:

Global Functions

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

translator()

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');

Type Definitions

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

Site, Page and File 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();

Translator Class Methods

The JohannSchopplich\ContentTranslator\Translator class provides a set of methods to copy and translate content programmatically. It is initialized when using the global translator() function or the translator() method on a Site, Page, or File model.

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. It accepts the target language and the source language as the first and second arguments.

$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. It accepts the content language, the target language, and the source language as the first, second, and third arguments. 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 = translator($page);
// Or use the translator method on the page model
$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. It accepts the content language, the target language, and the source language as the first, second, and third arguments. Note that 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. It accepts the content language, the target language, and the source language as the first, second, and third arguments.

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 to English
$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 will return a clone of the model. That's why you need to reassign the model to the variable you are using if you want to access the updated (translated) content.

To get the updated model, you can 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. In fact, the following configuration options are available and behave the same way as in the Panel:

• fieldTypes
• includeFields
• excludeFields

To pass the configuration to the Translator class, you can use the second argument of the translator() function or the translator() method on a Site, Page, or File model:

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

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

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