DeepL Client

Used internally by DeepLStrategy. Instantiate it directly when building a custom Strategy, overriding language mapping, or stubbing translation in tests.

Construction

use JohannSchopplich\ContentTranslator\DeepL;

$client = DeepL::instance();

DeepL::instance() returns a shared client; new DeepL() builds a fresh one. The constructor throws AuthException('Missing DeepL API key') when johannschopplich.content-translator.DeepL.apiKey is empty.

public function __construct(Closure|null $remote = null, Closure|null $delay = null)

public static function instance(): self
public static function reset(): void

Methods

translate

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

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

translateMany

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

Translates any number of texts in one call.

$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:

429 and 5xx responses are retried a few times before the error is raised. Every other error status throws on the first response.

A 200 whose body does not answer every text throws LogicException.

Language Code Resolution

A Kirby language code and its LC_ALL locale resolve to a DeepL target code as described under Supported Languages; a target code DeepL cannot name throws LogicException unless mapped via targetLanguageOverrides, while an unnamed source is omitted and DeepL detects it.

Request Options

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

return [
    'johannschopplich.content-translator' => [
        'DeepL' => [
            'apiKey' => 'your-deepl-api-key',
            'requestOptions' => [
                'formality' => 'more',
                'glossary_id' => 'YOUR_GLOSSARY_ID',
            ],
        ],
    ],
];