← Tillbaka till bloggen
Terminal window showing a Composer install command for the PolyLingo PHP SDK alongside a short PHP translate call and its JSON output.

Översätt strukturerat innehåll från PHP med PolyLingo SDK

By Robert M

Översätt strukturerat innehåll från PHP med PolyLingo SDK

PolyLingo PHP SDK finns nu tillgängligt på Packagist. Installera det med Composer, skicka in en sträng med vanlig text, Markdown, JSON eller HTML, och få tillbaka översättningar på alla språk du behöver — utan att skriva rå HTTP eller oroa dig för att din struktur ska förstöras under överföringen.

Det här inlägget täcker installation, autentisering och hela SDK:s yta: synkron översättning, batchförfrågningar, asynkrona jobb och felhantering.

Installation

Kräver PHP 7.4 eller senare. Installera via Composer:

composer require usepolylingo/polylingo

SDK:et är beroende av guzzlehttp/guzzle ^7.8 och psr/http-client ^1.0. Båda installeras automatiskt.

Ställa in klienten

Skapa en enda PolyLingo-instans och återanvänd den i hela din applikation. Det enda obligatoriska alternativet är din API-nyckel:

<?php
use PolyLingo\PolyLingo;

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

Spara din API-nyckel i en miljövariabel. Hårdkoda den aldrig eller checka in den i versionskontroll.

Två valfria inställningar som är bra att känna till:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // standard, skriv över för självhostade instanser
    'timeout' => 120_000,                           // millisekunder, standard är 120000 (2 minuter)
]);

Översätta innehåll

Vanlig text, Markdown, JSON eller HTML

Skicka in ditt innehåll och en array med målspråkskoder till translate(). Fältet format talar om för SDK vilket slags innehåll det handlar om:

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

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

Alternativet format accepterar plain, markdown, json eller html. Om du utelämnar det så känner API:et automatiskt av formatet från innehållet. Du kan också skicka en source-språkhint och ett model-värde av standard (standard) eller advanced.

Formatbevarande är det viktigaste beteendet här. För json-innehåll översätts endast strängvärden. Nycklar, nästlingar, arrayer och icke-strängtyper kommer tillbaka exakt som du skickade dem. För markdown förblir rubriker rubriker, kodblock lämnas verbatim och länk-URL:er ändras inte. För html bevaras taggar och attribut och endast textnoder översätts.

Översätta en JSON-lokalfil

Ett vanligt användningsfall är att översätta en lokalfil. Skicka hela objektet som en JSON-sträng:

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

En förfrågan hanterar alla tre lokaler. Nycklarna är orörda i varje utdatafil.

Batchförfrågningar

Använd batch() när du har flera separata innehållsobjekt att översätta. Du kan skicka upp till 100 objekt i en enda förfrågan, var och en med sin egen id och valfritt format:

$batch = $client->batch([
    'items' => [
        ['id' => 'hero_title',    'content' => 'Välkommen tillbaka',              'format' => 'plain'],
        ['id' => 'hero_subtitle', 'content' => 'Här är vad som är nytt idag',   'format' => 'plain'],
        ['id' => 'cta',           'content' => 'Kom igång',                     'format' => 'plain'],
    ],
    'targets' => ['es', 'fr'],
]);

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

Alla objekt delar samma targets-array. Svaret bevarar det id du skickade in för varje objekt, så att du kan mappa resultaten tillbaka till dina ursprungliga data utan att förlita dig på ordning.

Asynkrona jobb

För långvariga översättningar (stora dokument, många mål eller båda) accepterar jobb-API:et en förfrågan, returnerar omedelbart ett job_id och låter dig poll:a efter resultatet. SDK hanterar detta på två sätt.

Köa och poll:a manuellt

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

$jobId = $accepted['job_id'];

// Poll:a tills jobbet når ett terminalt status
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

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

Ett anrop som poll:ar tills klart

Om du inte behöver manuell kontroll hanterar jobs->translate() poll-loopen åt dig:

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

    // Valfria överskrivningar (standardvärden visas):
    // 'pollInterval' => 5000,       // ms mellan poll:ar, standard 5000
    // 'timeout'      => 1_200_000,  // total väntetid, standard 20 minuter
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Köposition: {$queuePosition}\n";
    // },
]);

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

onProgress-callbacken körs vid varje poll med aktuell köposition om API:et returnerar en, eller null om inte. Använd den för att logga framsteg eller uppdatera ett användargränssnitt.

Hjälpändpunkter

Tre lätta ändpunkter kräver inga parametrar utöver autentisering:

$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 och GET /languages kräver ingen API-nyckel. GET /usage returnerar tokenförbrukning för innevarande kalendermånad för det autentiserade kontot.

Felhantering

Alla SDK-fel ärver från PolyLingo\Errors\PolyLingoException. Fånga de specifika undertyper du vill hantera annorlunda:

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

try {
    $result = $client->translate([
        'content' => '# Hej',
        'targets' => ['es'],
        'format'  => 'markdown',
    ]);
} catch (AuthException $e) {
    // HTTP 401 — ogiltig, saknad eller återkallad API-nyckel
} catch (RateLimitException $e) {
    // HTTP 429 — minutgräns nådd
    $retryAfter = $e->getRetryAfter(); // int|null sekunder
} catch (JobFailedException $e) {
    // Asynkront jobb nådde ett felaktigt terminalt status
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Alla andra API-fel
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // t.ex. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() returnerar antal sekunder att vänta innan omförsök om API:et inkluderar den headern, eller null om inte. JobFailedException::getJobId() ger dig ID för det misslyckade jobbet så att du kan logga det eller visa det för användaren.

Snabbreferens

MetodEndpointKräver autentisering
$client->health()GET /healthNej
$client->languages()GET /languagesNej
$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 + pollingJa

Kom igång

SDK finns på Packagist på usepolylingo/polylingo. Fullständig API-dokumentation finns på usepolylingo.com/docs.

Gratisnivån inkluderar 50 000 tokens per månad. Ingen kreditkort krävs.

composer require usepolylingo/polylingo

Hämta din API-nyckel