Overview

A Strategy receives a list of TranslationUnits, returns translations in the same order, and stays stateless across calls. Built-in strategies handle batching and partial failures – per-unit failures keep source text and emit a warning hook; only zero survivors throw.

The Interface

namespace JohannSchopplich\ContentTranslator\Translation;

interface Strategy
{
    /**
     * @param list<TranslationUnit> $units
     * @return list<string|null>
     *
     * @throws TranslationException When zero units could be translated
     */
    public function execute(array $units, ExecutionOptions $options): array;
}

The contract is short: return one result per input in the same order, and stay stateless across calls. A unit you could not translate returns as null – the caller keeps its source text and records a rejection, so the drop reaches translation results instead of disappearing. Throw TranslationException only when zero units survived. The typed payloads passed in are TranslationUnit and ExecutionOptions.

Two things are handled for you, so a custom strategy never has to repeat them:

• Untranslatable text never arrives. Blanks, pure numbers, standalone URLs, and prose that is only KirbyTag placeholders are filtered out before execute() is called, and their source text is spliced back into the result. A batch with nothing else left never calls the strategy at all – so $units is never empty.
• The result is validated afterwards. Any unit that lost, invented or repeated a <cN/> token – and any slot that comes back null, blank, or as a non-string – is reverted to source and recorded as a rejection, whichever strategy produced it. Returning an empty string does not blank the field; it counts as a failed unit. The warning hook fires for the checks run here, but not for a slot you deliberately returned as null: you already know the reason, so emitting it is yours (see below).

Built-in Implementations

Strategy Resolution

Translator resolves the active strategy in this order, first match wins:

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

return [
    'johannschopplich.content-translator' => [
        'strategy' => 'deepl',
    ],
];

Implementing a Custom Strategy

Implement the interface, attempt each unit, and only throw when zero units survive – matching the failure pattern of the built-in strategies:

use JohannSchopplich\ContentTranslator\Translation\Exception\TranslationException;
use JohannSchopplich\ContentTranslator\Translation\ExecutionOptions;
use JohannSchopplich\ContentTranslator\Translation\Strategy;
use Kirby\Cms\App;

final class MyApiStrategy implements Strategy
{
    public function execute(array $units, ExecutionOptions $options): array
    {
        // A unit left `null` keeps its source text and is reported as a rejection
        $results = array_fill(0, count($units), null);
        $translatedCount = 0;
        $lastError = null;

        foreach ($units as $i => $unit) {
            try {
                $results[$i] = myTranslate(
                    text: $unit->text,
                    target: $options->targetLanguage->code,
                    source: $options->sourceLanguage?->code,
                );
                $translatedCount++;
            } catch (Throwable $error) {
                $lastError = $error;
                App::instance()->trigger('content-translator.translate:warning', [
                    'unit' => $unit,
                    'reason' => $error->getMessage(),
                    'previous' => $error,
                ]);
            }
        }

        if ($translatedCount === 0) {
            throw new TranslationException(
                strategy: 'my-api',
                reason: $lastError?->getMessage() ?? 'unknown error',
                unitsAttempted: count($units),
            );
        }

        return $results;
    }
}

The three moves to remember:

1. Leave a failed unit null – the caller keeps its source text and records the drop, so it shows up in translation results instead of passing as a translation. Pre-filling with source text still works, but the unit passes every check and is counted as translated, so the drop never reaches the result.
2. Emit content-translator.translate:warning for each unit you return as null – nothing else does, and the recorded rejection only says missing translation.
3. Throw TranslationException only when zero units survived – partial success is success.

Wire it up:

return [
    'johannschopplich.content-translator' => [
        'strategy' => new MyApiStrategy(),
    ],
];

This works as long as the constructor stays inert. A constructor that reads Kirby options or calls App::instance() runs too early here – wrap the instantiation in Kirby's ready callback instead, as shown under DeepLStrategy.