Traduci contenuti strutturati da PHP con PolyLingo SDK
By Robert M
Traduci contenuti strutturati da PHP con il PolyLingo SDK
Il PolyLingo PHP SDK è ora disponibile su Packagist. Installalo con Composer, fornisci una stringa di testo semplice, Markdown, JSON o HTML, e ricevi traduzioni in tutte le lingue di cui hai bisogno — senza scrivere HTTP raw o preoccuparti che la tua struttura venga danneggiata durante il trasferimento.
Questo post copre l'installazione, l'autenticazione e l'intera superficie dell'SDK: traduzione sincrona, richieste batch, lavori async e gestione degli errori.
Installazione
Richiede PHP 7.4 o superiore. Installa tramite Composer:
composer require usepolylingo/polylingo
L'SDK dipende da guzzlehttp/guzzle ^7.8 e psr/http-client ^1.0. Entrambi vengono installati automaticamente.
Configurazione del client
Crea una singola istanza PolyLingo e riutilizzala in tutta la tua applicazione. L'unica opzione richiesta è la tua chiave API:
<?php
use PolyLingo\PolyLingo;
$client = new PolyLingo([
'apiKey' => getenv('POLYLINGO_API_KEY'),
]);
Conserva la tua chiave API in una variabile d'ambiente. Non inserirla mai hardcoded o committarla nel controllo versione.
Due impostazioni opzionali da conoscere:
$client = new PolyLingo([
'apiKey' => getenv('POLYLINGO_API_KEY'),
'baseURL' => 'https://api.usepolylingo.com/v1', // default, sovrascrivi per istanze self-hosted
'timeout' => 120_000, // millisecondi, default 120000 (2 minuti)
]);
Traduzione dei contenuti
Testo semplice, Markdown, JSON o HTML
Passa il tuo contenuto e un array di codici lingua target a translate(). Il campo format indica all'SDK che tipo di contenuto sta gestendo:
$result = $client->translate([
'content' => '# Hello',
'targets' => ['es', 'fr', 'de'],
'format' => 'markdown',
]);
$es = $result['translations']['es'];
$tokens = $result['usage']['total_tokens'];
L'opzione format accetta plain, markdown, json o html. Se la ometti, l'API rileva automaticamente il formato dal contenuto. Puoi anche passare un suggerimento di lingua source e un valore model di standard (default) o advanced.
La preservazione del formato è il comportamento chiave qui. Per contenuti json, vengono tradotti solo i valori stringa. Chiavi, nidificazioni, array e tipi non stringa tornano esattamente come li hai inviati. Per markdown, le intestazioni rimangono intestazioni, i blocchi di codice sono lasciati verbatim e gli URL dei link non vengono toccati. Per html, tag e attributi sono preservati e solo i nodi di testo sono tradotti.
Tradurre un file locale JSON
Un caso d'uso comune è tradurre un file locale. Invia l'intero oggetto come stringa JSON:
$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"
);
}
Una singola richiesta gestisce tutte e tre le localizzazioni. Le chiavi non vengono modificate in nessun file di output.
Richieste batch
Usa batch() quando hai più elementi di contenuto separati da tradurre. Puoi inviare fino a 100 elementi in una singola richiesta, ciascuno con il proprio id e format opzionale:
$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";
}
Tutti gli elementi condividono lo stesso array targets. La risposta preserva l'id che hai passato per ogni elemento, così puoi mappare i risultati ai dati originali senza fare affidamento sull'ordine.
Lavori Async
Per traduzioni di lunga durata (documenti grandi, molti target o entrambi) l'API lavori accetta una richiesta, risponde immediatamente con un job_id e ti permette di fare polling per il risultato. L'SDK gestisce questo in due modi.
Metti in coda e fai polling manualmente
$accepted = $client->jobs->create([
'content' => file_get_contents('long-article.md'),
'targets' => ['es', 'fr', 'de', 'ja', 'zh'],
'format' => 'markdown',
]);
$jobId = $accepted['job_id'];
// Poll finché il lavoro non raggiunge uno stato terminale
do {
sleep(5);
$state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');
if ($state['status'] === 'complete') {
$translations = $state['translations'];
}
Una chiamata che fa polling fino al completamento
Se non ti serve il controllo manuale, jobs->translate() gestisce il ciclo di polling per te:
$done = $client->jobs->translate([
'content' => file_get_contents('long-article.md'),
'targets' => ['es', 'fr', 'de'],
'format' => 'markdown',
// Override opzionali (default mostrati):
// 'pollInterval' => 5000, // ms tra i polling, default 5000
// 'timeout' => 1_200_000, // budget totale di attesa, default 20 minuti
// 'onProgress' => function (?int $queuePosition) {
// echo "Posizione in coda: {$queuePosition}\n";
// },
]);
$translations = $done['translations'];
$usage = $done['usage'];
La callback onProgress viene chiamata ad ogni polling con la posizione attuale in coda se l'API la restituisce, o null se non disponibile. Usala per registrare i progressi o aggiornare un'interfaccia utente.
Endpoint utilità
Tre endpoint leggeri non richiedono parametri oltre all'autenticazione:
$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 e GET /languages non richiedono chiave API. GET /usage restituisce il consumo di token per il mese solare corrente per l'account autenticato.
Gestione degli errori
Tutti gli errori dell'SDK estendono PolyLingo\Errors\PolyLingoException. Cattura i sottotipi specifici che vuoi gestire diversamente:
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 — chiave API non valida, mancante o revocata
} catch (RateLimitException $e) {
// HTTP 429 — limite per minuto raggiunto
$retryAfter = $e->getRetryAfter(); // int|null secondi
} catch (JobFailedException $e) {
// Lavoro async ha raggiunto uno stato terminale fallito
$jobId = $e->getJobId();
} catch (PolyLingoException $e) {
// Tutti gli altri errori API
$httpStatus = $e->getHttpStatus();
$errorCode = $e->getErrorCode(); // es. "invalid_request", "translation_error"
}
RateLimitException::getRetryAfter() restituisce il numero di secondi da attendere prima di riprovare se l'API include quell'intestazione, o null se non presente. JobFailedException::getJobId() ti dà l'ID del lavoro fallito così puoi registrarlo o mostrarlo all'utente.
Riferimento rapido
| Metodo | Endpoint | Auth richiesta |
|---|---|---|
$client->health() | GET /health | No |
$client->languages() | GET /languages | No |
$client->translate() | POST /translate | Sì |
$client->batch() | POST /translate/batch | Sì |
$client->usage() | GET /usage | Sì |
$client->jobs->create() | POST /jobs | Sì |
$client->jobs->get($id) | GET /jobs/:id | Sì |
$client->jobs->translate() | POST /jobs + polling | Sì |
Inizia
L'SDK è su Packagist a usepolylingo/polylingo. La documentazione completa dell'API è su usepolylingo.com/docs.
Il piano gratuito include 50.000 token al mese. Nessuna carta di credito richiesta.
composer require usepolylingo/polylingo