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>
     *
     * @throws TranslationException When zero units could be translated.
     */
    public function execute(array $units, ExecutionOptions $options): array;
}

The contract is short: return one translation per input in the same order, and stay stateless across calls. Throw TranslationException only when zero units survived – per-unit failures keep the source text and trigger content-translator.translate:warning. 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 or invented a <cN/> token – and any slot that comes back missing or as a non-string – is reverted to source and reported through the warning hook, whichever strategy produced it.

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 JohannSchopplich\ContentTranslator\Translation\TranslationUnit;
use Kirby\Cms\App;

final class MyApiStrategy implements Strategy
{
    public function execute(array $units, ExecutionOptions $options): array
    {
        // Pre-fill with source so failed units keep the original text
        $results = array_map(fn (TranslationUnit $u) => $u->text, $units);
        $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. Pre-fill $results with source text so a per-unit failure preserves the existing content.
2. Emit content-translator.translate:warning for each dropped unit – listeners can log or alert.
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.