← Zurück zum Blog
Terminal window showing a Composer install command for the PolyLingo PHP SDK alongside a short PHP translate call and its JSON output.

Strukturierte Inhalte aus PHP mit dem PolyLingo SDK übersetzen

By Robert M

Übersetzen strukturierter Inhalte aus PHP mit dem PolyLingo SDK

Das PolyLingo PHP SDK ist jetzt auf Packagist verfügbar. Installieren Sie es mit Composer, übergeben Sie ihm einen String aus einfachem Text, Markdown, JSON oder HTML und erhalten Sie Übersetzungen in jeder gewünschten Sprache — ohne rohes HTTP schreiben oder sich Sorgen machen zu müssen, dass Ihre Struktur beim Transport beschädigt wird.

Dieser Beitrag behandelt Installation, Authentifizierung und die gesamte Oberfläche des SDK: synchrone Übersetzung, Batch-Anfragen, asynchrone Jobs und Fehlerbehandlung.

Installation

Erfordert PHP 7.4 oder höher. Installation über Composer:

composer require usepolylingo/polylingo

Das SDK hängt von guzzlehttp/guzzle ^7.8 und psr/http-client ^1.0 ab. Beide werden automatisch mitinstalliert.

Einrichtung des Clients

Erstellen Sie eine einzelne PolyLingo-Instanz und verwenden Sie sie in Ihrer gesamten Anwendung wieder. Die einzige erforderliche Option ist Ihr API-Schlüssel:

<?php
use PolyLingo\PolyLingo;

$client = new PolyLingo([
    'apiKey' => getenv('POLYLINGO_API_KEY'),
]);

Speichern Sie Ihren API-Schlüssel in einer Umgebungsvariable. Niemals hartkodieren oder in die Versionskontrolle einchecken.

Zwei optionale Einstellungen, die Sie kennen sollten:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // Standard, überschreiben für selbstgehostete Instanzen
    'timeout' => 120_000,                           // Millisekunden, Standard ist 120000 (2 Minuten)
]);

Inhalte übersetzen

Einfacher Text, Markdown, JSON oder HTML

Übergeben Sie Ihren Inhalt und ein Array von Zielsprachcodes an translate(). Das Feld format teilt dem SDK mit, mit welcher Art von Inhalt es zu tun hat:

$result = $client->translate([
    'content' => '# Hello',
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',
]);

$es     = $result['translations']['es'];
$tokens = $result['usage']['total_tokens'];

Die Option format akzeptiert plain, markdown, json oder html. Wenn Sie sie weglassen, erkennt die API das Format automatisch anhand des Inhalts. Sie können auch einen source-Sprachhinweis und einen model-Wert von standard (Standard) oder advanced übergeben.

Die Format-Erhaltung ist hier das Schlüsselverhalten. Bei json-Inhalten werden nur String-Werte übersetzt. Schlüssel, Verschachtelungen, Arrays und Nicht-String-Typen bleiben genau so erhalten, wie Sie sie gesendet haben. Bei markdown bleiben Überschriften Überschriften, Codeblöcke werden unverändert gelassen und Link-URLs werden nicht verändert. Bei html werden Tags und Attribute erhalten und nur Textknoten übersetzt.

Übersetzen einer JSON-Lokalisierungsdatei

Ein häufiger Anwendungsfall ist das Übersetzen einer Lokalisierungsdatei. Senden Sie das gesamte Objekt als JSON-String:

$source = json_decode(file_get_contents('messages/en.json'), true);

$result = $client->translate([
    'content' => json_encode($source),
    'format'  => 'json',
    'targets' => ['de', 'fr', 'ja'],
]);

foreach (['de', 'fr', 'ja'] as $locale) {
    $translated = json_decode($result['translations'][$locale], true);
    file_put_contents(
        "messages/{$locale}.json",
        json_encode($translated, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n"
    );
}

Eine Anfrage verarbeitet alle drei Lokale. Schlüssel bleiben in jeder Ausgabedatei unverändert.

Batch-Anfragen

Verwenden Sie batch(), wenn Sie mehrere separate Inhalte übersetzen möchten. Sie können bis zu 100 Elemente in einer einzigen Anfrage senden, jedes mit eigener id und optionalem format:

$batch = $client->batch([
    'items' => [
        ['id' => 'hero_title',    'content' => 'Welcome back',              'format' => 'plain'],
        ['id' => 'hero_subtitle', 'content' => 'Here is what is new today', 'format' => 'plain'],
        ['id' => 'cta',           'content' => 'Get started',               'format' => 'plain'],
    ],
    'targets' => ['es', 'fr'],
]);

foreach ($batch['results'] as $row) {
    echo $row['id'] . ': ' . $row['translations']['es'] . "\n";
}

Alle Elemente teilen sich dasselbe targets-Array. Die Antwort bewahrt die id, die Sie für jedes Element übergeben haben, sodass Sie Ergebnisse ohne Reihenfolgeabhängigkeit auf Ihre Originaldaten zurückführen können.

Asynchrone Jobs

Für lang laufende Übersetzungen (große Dokumente, viele Ziele oder beides) akzeptiert die Jobs-API eine Anfrage, gibt sofort eine job_id zurück und ermöglicht Ihnen, das Ergebnis abzufragen. Das SDK unterstützt dies auf zwei Arten.

Manuelles Einreihen und Abfragen

$accepted = $client->jobs->create([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de', 'ja', 'zh'],
    'format'  => 'markdown',
]);

$jobId = $accepted['job_id'];

// Abfragen, bis der Job einen Endstatus erreicht
 do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

if ($state['status'] === 'complete') {
    $translations = $state['translations'];
}

Ein Aufruf, der bis zum Abschluss abfragt

Wenn Sie keine manuelle Steuerung benötigen, übernimmt jobs->translate() die Abfrageschleife für Sie:

$done = $client->jobs->translate([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',

    // Optionale Überschreibungen (Standardwerte gezeigt):
    // 'pollInterval' => 5000,       // ms zwischen Abfragen, Standard 5000
    // 'timeout'      => 1_200_000,  // Gesamtwartezeit, Standard 20 Minuten
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);

$translations = $done['translations'];
$usage        = $done['usage'];

Der onProgress-Callback wird bei jeder Abfrage mit der aktuellen Position in der Warteschlange aufgerufen, falls die API diese zurückgibt, oder null, wenn nicht verfügbar. Verwenden Sie ihn, um Fortschritte zu protokollieren oder eine UI zu aktualisieren.

Dienstendpunkte

Drei leichte Endpunkte benötigen keine Parameter außer der Authentifizierung:

$health = $client->health();
// ['status' => 'ok', 'timestamp' => '...']

$langs = $client->languages();
// ['languages' => [['code' => 'en', 'name' => 'English', 'rtl' => false], ...]]

$usage = $client->usage();
// ['usage' => ['tokens_used' => 12000, 'tokens_remaining' => 88000, ...]]

GET /health und GET /languages benötigen keinen API-Schlüssel. GET /usage gibt den Tokenverbrauch für den aktuellen Kalendermonat für das authentifizierte Konto zurück.

Fehlerbehandlung

Alle SDK-Fehler erweitern PolyLingo\Errors\PolyLingoException. Fangen Sie die spezifischen Subtypen, die Sie unterschiedlich behandeln möchten:

use PolyLingo\Errors\AuthException;
use PolyLingo\Errors\JobFailedException;
use PolyLingo\Errors\PolyLingoException;
use PolyLingo\Errors\RateLimitException;

try {
    $result = $client->translate([
        'content' => '# Hello',
        'targets' => ['es'],
        'format'  => 'markdown',
    ]);
} catch (AuthException $e) {
    // HTTP 401 — ungültiger, fehlender oder widerrufener API-Schlüssel
} catch (RateLimitException $e) {
    // HTTP 429 — Minutenlimit erreicht
    $retryAfter = $e->getRetryAfter(); // int|null Sekunden
} catch (JobFailedException $e) {
    // Asynchroner Job erreichte einen fehlgeschlagenen Endstatus
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Alle anderen API-Fehler
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // z.B. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() gibt die Anzahl der Sekunden zurück, die vor einem erneuten Versuch gewartet werden soll, falls die API diesen Header enthält, oder null, wenn nicht vorhanden. JobFailedException::getJobId() gibt die ID des fehlgeschlagenen Jobs zurück, damit Sie ihn protokollieren oder dem Benutzer anzeigen können.

Schnellübersicht

MethodeEndpunktAuth erforderlich
$client->health()GET /healthNein
$client->languages()GET /languagesNein
$client->translate()POST /translateJa
$client->batch()POST /translate/batchJa
$client->usage()GET /usageJa
$client->jobs->create()POST /jobsJa
$client->jobs->get($id)GET /jobs/:idJa
$client->jobs->translate()POST /jobs + AbfrageJa

Erste Schritte

Das SDK ist auf Packagist unter usepolylingo/polylingo verfügbar. Die vollständige API-Dokumentation finden Sie unter usepolylingo.com/docs.

Der kostenlose Tarif umfasst 50.000 Tokens pro Monat. Keine Kreditkarte erforderlich.

composer require usepolylingo/polylingo

Holen Sie sich Ihren API-Schlüssel