DeepL Client

Talk to the DeepL API directly from PHP – translation requests, language code resolution, retry handling. Used internally by DeepLStrategy – reach for it when building a custom strategy, overriding language mapping, or testing.

Construction

use JohannSchopplich\ContentTranslator\DeepL;

$client = DeepL::instance();

The cached singleton reads johannschopplich.content-translator.DeepL.apiKey once. The constructor throws AuthException('Missing DeepL API key') when the key is empty.

Methods

translate

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

Convenience wrapper around translateMany([$text], …).

translateMany

public function translateMany(array $texts, string $targetLanguage, string|null $sourceLanguage = null): array

Send up to N texts. The client auto-chunks into requests of 50 texts each and merges the results.

$translations = DeepL::instance()->translateMany(
    ['Hello', 'Goodbye', 'Thank you'],
    'de',
    'en'
);
// ['Hallo', 'Auf Wiedersehen', 'Danke']

Error Handling

The client maps DeepL HTTP responses to typed exceptions:

5xx and 429/529 responses are retried automatically with exponential backoff (max 5 attempts, capped at 8 seconds).

Language Code Resolution

The target language is resolved against the configured Kirby language's LC_ALL locale, then matched against DeepL's supported target languages.

When the resolved code isn't in SUPPORTED_TARGET_LANGUAGES, the constructor throws LogicException.

Request Options

Custom request options merge into every translate call. See DeepL request body parameters.

return [
    'johannschopplich.content-translator' => [
        'DeepL' => [
            'apiKey' => env('DEEPL_API_KEY'),
            'requestOptions' => [
                'formality' => 'more',
                'glossary_id' => 'YOUR_GLOSSARY_ID',
            ],
        ],
    ],
];