Exceptions

TranslationException is the plugin's own; the rest are Kirby's. All extend Kirby\Exception\Exception and serialize cleanly to API responses. TranslationException fires only when zero units could be translated – partial failures emit a :warning hook instead.

TranslationException

JohannSchopplich\ContentTranslator\Translation\Exception\TranslationException extends Kirby\Exception\Exception. Built-in strategies throw it when zero units survived – per-unit failures keep the source text and only emit a :warning hook.

public function __construct(
    string $strategy,
    string $reason,
    int $unitsAttempted,
    int $unitsTranslated = 0,
)

Details Payload

The exception carries structured details for logging:

For per-unit error context, listen to content-translator.translate:warning – it fires for each failed unit with the underlying Throwable before the strategy decides whether enough units survived.

Catching

use JohannSchopplich\ContentTranslator\Translation\Exception\TranslationException;

try {
    $translator->translateContent('de', 'de', 'en');
} catch (TranslationException $error) {
    $details = $error->getDetails();
    // ['strategy' => 'deepl', 'unitsAttempted' => 12, 'unitsTranslated' => 0]
}

An unhandled TranslationException reaches the Panel as HTTP 502.

LogicException

Configuration errors throw Kirby\Exception\LogicException:

A language that resolves to no DeepL code needs a language code override. Other DeepL HTTP error responses map to LogicException – see the DeepL client reference.

InvalidArgumentException

Kirby\Exception\InvalidArgumentException is thrown for a language code the site does not know:

Both the translate() helper and Translator::translateText() resolve their $targetLanguage and $sourceLanguage against Kirby's language registry, so a typo in a script surfaces here rather than as a failed request. A single-language site skips the check – any code is passed on to the strategy.

AuthException

Kirby\Exception\AuthException is thrown for missing or rejected API keys: