Vertaal gestructureerde inhoud uit PHP met de PolyLingo SDK
By Robert M
Vertaal gestructureerde inhoud vanuit PHP met de PolyLingo SDK
De PolyLingo PHP SDK is nu beschikbaar op Packagist. Installeer het met Composer, geef het een string met platte tekst, Markdown, JSON of HTML, en krijg vertalingen terug in elke taal die je nodig hebt — zonder ruwe HTTP te schrijven of je zorgen te maken dat je structuur onderweg beschadigd raakt.
Deze post behandelt installatie, authenticatie en het volledige oppervlak van de SDK: synchrone vertaling, batchverzoeken, async taken en foutafhandeling.
Installatie
Vereist PHP 7.4 of hoger. Installeer via Composer:
composer require usepolylingo/polylingo
De SDK is afhankelijk van guzzlehttp/guzzle ^7.8 en psr/http-client ^1.0. Beide worden automatisch geïnstalleerd.
De client instellen
Maak een enkele PolyLingo instantie aan en hergebruik deze in je applicatie. De enige vereiste optie is je API-sleutel:
<?php
use PolyLingo\PolyLingo;
$client = new PolyLingo([
'apiKey' => getenv('POLYLINGO_API_KEY'),
]);
Bewaar je API-sleutel in een omgevingsvariabele. Hardcode deze nooit of commit deze niet in versiebeheer.
Twee optionele instellingen die het waard zijn om te weten:
$client = new PolyLingo([
'apiKey' => getenv('POLYLINGO_API_KEY'),
'baseURL' => 'https://api.usepolylingo.com/v1', // standaard, overschrijven voor zelf-gehoste instanties
'timeout' => 120_000, // milliseconden, standaard is 120000 (2 minuten)
]);
Inhoud vertalen
Platte tekst, Markdown, JSON of HTML
Geef je inhoud en een array van doeltaalcodes door aan translate(). Het veld format vertelt de SDK met welk soort inhoud het te maken heeft:
$result = $client->translate([
'content' => '# Hello',
'targets' => ['es', 'fr', 'de'],
'format' => 'markdown',
]);
$es = $result['translations']['es'];
$tokens = $result['usage']['total_tokens'];
De optie format accepteert plain, markdown, json of html. Als je het weglaat, detecteert de API het formaat automatisch aan de hand van de inhoud. Je kunt ook een source taalhint en een model waarde van standard (standaard) of advanced meegeven.
Het behouden van het formaat is hier het belangrijkste gedrag. Voor json inhoud worden alleen stringwaarden vertaald. Sleutels, nesting, arrays en niet-string types komen exact terug zoals je ze hebt gestuurd. Voor markdown blijven koppen koppen, codeblokken blijven letterlijk, en link-URL's worden niet aangeraakt. Voor html worden tags en attributen behouden en alleen tekstknopen vertaald.
Een JSON locale-bestand vertalen
Een veelvoorkomend gebruik is het vertalen van een locale-bestand. Stuur het hele object als een 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"
);
}
Eén verzoek behandelt alle drie de locales. Sleutels blijven onaangeroerd in elk uitvoerbestand.
Batchverzoeken
Gebruik batch() wanneer je meerdere afzonderlijke inhoudsitems hebt om te vertalen. Je kunt tot 100 items in één verzoek sturen, elk met een eigen id en optioneel 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 items delen dezelfde targets array. De respons behoudt de id die je hebt meegegeven voor elk item, zodat je resultaten kunt terugkoppelen naar je originele data zonder op volgorde te vertrouwen.
Async taken
Voor langlopende vertalingen (grote documenten, veel doelen, of beide) accepteert de jobs API een verzoek, geeft direct een job_id terug, en laat je pollen voor het resultaat. De SDK behandelt dit op twee manieren.
Handmatig in de wachtrij zetten en pollen
$accepted = $client->jobs->create([
'content' => file_get_contents('long-article.md'),
'targets' => ['es', 'fr', 'de', 'ja', 'zh'],
'format' => 'markdown',
]);
$jobId = $accepted['job_id'];
// Poll totdat de taak een eindstatus bereikt
do {
sleep(5);
$state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');
if ($state['status'] === 'complete') {
$translations = $state['translations'];
}
Eén oproep die blijft pollen tot klaar
Als je geen handmatige controle nodig hebt, handelt jobs->translate() de polling loop voor je af:
$done = $client->jobs->translate([
'content' => file_get_contents('long-article.md'),
'targets' => ['es', 'fr', 'de'],
'format' => 'markdown',
// Optionele overschrijvingen (standaardwaarden getoond):
// 'pollInterval' => 5000, // ms tussen polls, standaard 5000
// 'timeout' => 1_200_000, // totale wachttijd, standaard 20 minuten
// 'onProgress' => function (?int $queuePosition) {
// echo "Queue position: {$queuePosition}\n";
// },
]);
$translations = $done['translations'];
$usage = $done['usage'];
De onProgress callback wordt bij elke poll aangeroepen met de huidige wachtrijpositie als de API die teruggeeft, of null als die niet beschikbaar is. Gebruik het om voortgang te loggen of een UI bij te werken.
Hulppunten
Drie lichte eindpunten hebben geen parameters nodig behalve authenticatie:
$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 en GET /languages vereisen geen API-sleutel. GET /usage geeft tokenverbruik terug voor de huidige kalendermaand voor het geauthenticeerde account.
Foutafhandeling
Alle SDK-fouten breiden PolyLingo\Errors\PolyLingoException uit. Vang de specifieke subtypes die je anders wilt afhandelen:
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 — ongeldige, ontbrekende of ingetrokken API-sleutel
} catch (RateLimitException $e) {
// HTTP 429 — per-minuut limiet bereikt
$retryAfter = $e->getRetryAfter(); // int|null seconden
} catch (JobFailedException $e) {
// Async taak bereikte een mislukte eindstatus
$jobId = $e->getJobId();
} catch (PolyLingoException $e) {
// Alle andere API-fouten
$httpStatus = $e->getHttpStatus();
$errorCode = $e->getErrorCode(); // bijv. "invalid_request", "translation_error"
}
RateLimitException::getRetryAfter() geeft het aantal seconden terug om te wachten voordat opnieuw geprobeerd wordt als de API die header bevat, of null als die niet aanwezig is. JobFailedException::getJobId() geeft je de ID van de mislukte taak zodat je die kunt loggen of aan de gebruiker kunt tonen.
Snelle referentie
| Methode | Eindpunt | Auth vereist |
|---|---|---|
$client->health() | GET /health | Nee |
$client->languages() | GET /languages | Nee |
$client->translate() | POST /translate | Ja |
$client->batch() | POST /translate/batch | Ja |
$client->usage() | GET /usage | Ja |
$client->jobs->create() | POST /jobs | Ja |
$client->jobs->get($id) | GET /jobs/:id | Ja |
$client->jobs->translate() | POST /jobs + polling | Ja |
Aan de slag
De SDK staat op Packagist bij usepolylingo/polylingo. Volledige API-documentatie is te vinden op usepolylingo.com/docs.
De gratis laag bevat 50.000 tokens per maand. Geen creditcard vereist.
composer require usepolylingo/polylingo