Překlad strukturovaného obsahu z PHP pomocí PolyLingo SDK

PolyLingo PHP SDK je nyní dostupné na Packagist. Nainstalujte jej pomocí Composeru, předáte mu řetězec prostého textu, Markdown, JSON nebo HTML a získáte zpět překlady do všech jazyků, které potřebujete — bez psaní surových HTTP požadavků nebo obav o poškození struktury během přenosu.

Tento příspěvek pokrývá instalaci, autentizaci a kompletní funkce SDK: synchronní překlad, dávkové požadavky, asynchronní úlohy a zpracování chyb.

---

Instalace

Vyžaduje PHP 7.4 nebo novější. Instalace přes Composer:

composer require usepolylingo/polylingo

SDK závisí na guzzlehttp/guzzle ^7.8 a psr/http-client ^1.0. Oba balíčky jsou automaticky staženy.

---

Nastavení klienta

Vytvořte jednu instanci PolyLingo a znovu ji použijte v celé aplikaci. Jedinou povinnou volbou je váš API klíč:

<?php
use PolyLingo\PolyLingo;

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

Uložte svůj API klíč do proměnné prostředí. Nikdy jej nezapisujte přímo do kódu ani neukládejte do verzovacího systému.

Dvě volitelné nastavení, která stojí za zmínku:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // výchozí, přepište pro self-hosted instance
    'timeout' => 120_000,                           // milisekundy, výchozí je 120000 (2 minuty)
]);

---

Překlad obsahu

Prostý text, Markdown, JSON nebo HTML

Předáte obsah a pole cílových jazykových kódů do translate(). Pole format říká SDK, s jakým typem obsahu pracuje:

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

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

Volba format přijímá hodnoty plain, markdown, json nebo html. Pokud ji vynecháte, API automaticky detekuje formát z obsahu. Můžete také předat jazykový tip source a hodnotu model standard (výchozí) nebo advanced.

Zachování formátu je zde klíčové. U obsahu json jsou překládány pouze textové hodnoty. Klíče, vnoření, pole a netextové typy zůstávají přesně tak, jak jste je poslali. U markdown zůstávají nadpisy nadpisy, bloky kódu jsou ponechány beze změny a URL odkazů se nedotýkáme. U html jsou značky a atributy zachovány a překládají se pouze textové uzly.

Překlad JSON lokalizačního souboru

Běžným případem je překlad lokalizačního souboru. Pošlete celý objekt jako JSON řetězec:

$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"
    );
}

Jeden požadavek zpracuje všechny tři lokalizace. Klíče zůstávají v každém výstupním souboru nezměněné.

---

Dávkové požadavky

Použijte batch(), když máte více samostatných položek obsahu k překladu. Můžete poslat až 100 položek v jednom požadavku, každou se svým id a volitelným 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";
}

Všechny položky sdílejí stejné pole targets. Odpověď zachovává id, které jste poslali pro každou položku, takže můžete výsledky mapovat zpět na původní data bez závislosti na pořadí.

---

Asynchronní úlohy

Pro dlouhotrvající překlady (velké dokumenty, mnoho cílů nebo obojí) API úloh přijme požadavek, okamžitě vrátí job_id a umožní vám dotazovat se na výsledek. SDK to řeší dvěma způsoby.

Zařazení do fronty a manuální dotazování

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

$jobId = $accepted['job_id'];

// Dotazujte se, dokud úloha nedosáhne konečného stavu
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

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

Jeden hovor, který dotazuje, dokud není hotovo

Pokud nepotřebujete manuální kontrolu, jobs->translate() za vás zvládne smyčku dotazování:

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

    // Volitelné přepsání (výchozí hodnoty):
    // 'pollInterval' => 5000,       // ms mezi dotazy, výchozí 5000
    // 'timeout'      => 1_200_000,  // celkový čas čekání, výchozí 20 minut
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);

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

Callback onProgress se spouští při každém dotazu s aktuální pozicí ve frontě, pokud ji API vrátí, nebo null, pokud není dostupná. Použijte ji pro logování průběhu nebo aktualizaci uživatelského rozhraní.

---

Pomocné koncové body

Tři lehké koncové body nepotřebují žádné parametry kromě autentizace:

$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 a GET /languages nevyžadují API klíč. GET /usage vrací spotřebu tokenů za aktuální kalendářní měsíc pro autentizovaný účet.

---

Zpracování chyb

Všechny chyby SDK dědí z PolyLingo\Errors\PolyLingoException. Zachyťte konkrétní podtypy, které chcete zpracovat odlišně:

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 — neplatný, chybějící nebo odvolaný API klíč
} catch (RateLimitException $e) {
    // HTTP 429 — dosažen limit za minutu
    $retryAfter = $e->getRetryAfter(); // int|null v sekundách
} catch (JobFailedException $e) {
    // Asynchronní úloha dosáhla chybového konečného stavu
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Všechny ostatní chyby API
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // např. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() vrací počet sekund, které je třeba počkat před opakováním, pokud API zahrnuje tento hlavičkový údaj, nebo null, pokud není přítomen. JobFailedException::getJobId() vám dává ID neúspěšné úlohy, abyste ji mohli zaznamenat nebo zobrazit uživateli.

---

Rychlá reference

Metoda	Endpoint	Vyžaduje autentizaci
$client->health()	GET /health	Ne
$client->languages()	GET /languages	Ne
$client->translate()	POST /translate	Ano
$client->batch()	POST /translate/batch	Ano
$client->usage()	GET /usage	Ano
$client->jobs->create()	POST /jobs	Ano
$client->jobs->get($id)	GET /jobs/:id	Ano
$client->jobs->translate()	POST /jobs + polling	Ano

---

Začněte

SDK je na Packagist na usepolylingo/polylingo. Kompletní dokumentace API je na usepolylingo.com/docs.

Bezplatná úroveň zahrnuje 50 000 tokenů měsíčně. Kreditní karta není potřeba.

composer require usepolylingo/polylingo

Získejte svůj API klíč