Hooks

The plugin exposes three Kirby hooks. They fire for every individual text the pipeline processes – including text inside blocks, structures, layouts, and table cells.

On the paths where they do fire, :before and :after run for every unit holding content, including values no provider ever sees – a field that is just a price or a URL still runs both hooks, with the text unchanged. Inspect $text if a hook should only act on prose.

content-translator.translate:before

Rewrite text on its way to the strategy. The returned string replaces the unit's text and is always sent on – the hook cannot skip a unit or cancel the translation. To keep content out of translation entirely, narrow fieldTypes or list the field in excludeFields.

return [
    'hooks' => [
        'content-translator.translate:before' => function ($text) {
            // Strip internal editorial markers so they never reach the provider
            return str_replace(['[draft]', '[review]'], '', $text);
        }
    ]
];

content-translator.translate:after

Postprocess translated text – language-specific formatting, terminology enforcement, logging.

return [
    'hooks' => [
        'content-translator.translate:after' => function ($text, $originalText, $targetLanguage) {
            // Restore untranslatable terms
            $protected = ['API', 'CSS', 'HTML', 'JavaScript'];
            foreach ($protected as $term) {
                $text = preg_replace('/\b' . $term . '\b/i', $term, $text);
            }

            return $text;
        }
    ]
];

content-translator.translate:warning

Fires once per unit that was dropped. The unit keeps its source text. Silent by default – wire it to logging, Sentry, or Slack to surface drops in production.

How much survives depends on where the drop happened. missing translation, non-string translation, empty translation and placeholder mismatch are caught after the strategy returns, so they apply to every strategy – including a custom one – and only the affected unit is reverted. The remaining reasons come from the strategy itself: CopilotAIStrategy drops per unit and per chunk, so the rest of the batch still gets written, while DeepLStrategy sends the batch in one request and, when it fails, fires a warning for every unit and then throws TranslationException, so nothing from that batch is stored. Treat a DeepL warning as a batch-level failure that happens to be reported per unit.

Drop Reasons

Example: Send Drops to Sentry

use Sentry\State\Scope;
use function Sentry\captureMessage;
use function Sentry\withScope;

return [
    'hooks' => [
        'content-translator.translate:warning' => function ($unit, $reason, $previous) {
            withScope(function (Scope $scope) use ($unit, $reason, $previous) {
                $scope->setExtra('field', $unit->fieldKey);
                $scope->setExtra('text_excerpt', mb_substr($unit->text, 0, 200));

                if ($previous !== null) {
                    $scope->setExtra('upstream_error', $previous->getMessage());
                }

                captureMessage('Translation dropped: ' . $reason);
            });
        },
    ],
];

Field-Aware Preprocessing

The unit payload key lets you branch on the originating field. fieldKey is only filled in when the translation walks a model's content – that is translateContent() and the CLI. Panel translations post a flat list of texts to the batch endpoint, and standalone translateTexts() calls carry no field context either, so fieldKey is null in both cases. The example below stays safe either way, because a null key never matches:

return [
    'hooks' => [
        'content-translator.translate:before' => function ($text, $targetLanguage, $sourceLanguage, $type, $unit) {
            // Tighter prompts for headlines
            if (in_array($unit->fieldKey, ['headline', 'title'], true)) {
                return trim($text);
            }

            return $text;
        }
    ]
];

Notes

Hooks fire for every individual text – they may run hundreds of times during a batch translation. Keep them fast.