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

Oversett strukturert innhold fra PHP med PolyLingo SDK

By Robert M

Oversett strukturert innhold fra PHP med PolyLingo SDK

PolyLingo PHP SDK er nå tilgjengelig på Packagist. Installer den med Composer, gi den en streng med ren tekst, Markdown, JSON eller HTML, og få tilbake oversettelser på alle språk du trenger — uten å skrive rå HTTP eller bekymre deg for at strukturen din blir ødelagt underveis.

Dette innlegget dekker installasjon, autentisering og hele SDK-overflaten: synkron oversettelse, batch-forespørsler, asynkrone jobber og feilhåndtering.

Installasjon

Krever PHP 7.4 eller nyere. Installer via Composer:

composer require usepolylingo/polylingo

SDK-en avhenger av guzzlehttp/guzzle ^7.8 og psr/http-client ^1.0. Begge blir automatisk installert.

Sette opp klienten

Lag en enkelt PolyLingo-instans og gjenbruk den i hele applikasjonen din. Det eneste påkrevde alternativet er API-nøkkelen din:

<?php
use PolyLingo\PolyLingo;
 
$client = new PolyLingo([
    'apiKey' => getenv('POLYLINGO_API_KEY'),
]);

Lagre API-nøkkelen din i en miljøvariabel. Aldri hardkod den eller legg den i versjonskontroll.

To valgfrie innstillinger det er verdt å vite om:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // standard, overskriv for selvhostede instanser
    'timeout' => 120_000,                           // millisekunder, standard er 120000 (2 minutter)
]);

Oversette innhold

Ren tekst, Markdown, JSON eller HTML

Send innholdet ditt og en liste med målspråkkoder til translate(). Feltet format forteller SDK hvilken type innhold det håndterer:

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

format-valget godtar plain, markdown, json eller html. Hvis du utelater det, oppdager API-et formatet automatisk fra innholdet. Du kan også sende en source språkhint og en model verdi av standard (standard) eller advanced.

Bevaring av format er nøkkeloppførselen her. For json-innhold oversettes bare strengverdier. Nøkler, nesting, arrayer og ikke-streng-typer kommer tilbake nøyaktig som du sendte dem. For markdown forblir overskrifter overskrifter, kodeblokker blir stående verbatim, og lenke-URL-er berøres ikke. For html bevares tagger og attributter, og bare tekstnoder oversettes.

Oversette en JSON locale-fil

Et vanlig brukstilfelle er å oversette en locale-fil. Send hele objektet som en JSON-streng:

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

Én forespørsel håndterer alle tre locale. Nøkler forblir urørt i hver utdatafil.

Batch-forespørsler

Bruk batch() når du har flere separate innholdsobjekter å oversette. Du kan sende opptil 100 elementer i én forespørsel, hver med sin egen id og valgfri 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 elementer deler samme targets-array. Responsen bevarer id du sendte inn for hvert element, slik at du kan koble resultater tilbake til originaldataene dine uten å stole på rekkefølge.

Async jobber

For langvarige oversettelser (store dokumenter, mange mål, eller begge deler) godtar jobs-API-et en forespørsel, returnerer umiddelbart med en job_id, og lar deg poll'e etter resultatet. SDK-en håndterer dette på to måter.

Kjø inn i kø og poll manuelt

$accepted = $client->jobs->create([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de', 'ja', 'zh'],
    'format'  => 'markdown',
]);
 
$jobId = $accepted['job_id'];
 
// Poll til jobben når en terminal status
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');
 
if ($state['status'] === 'complete') {
    $translations = $state['translations'];
}

Ett kall som poller til ferdig

Hvis du ikke trenger manuell kontroll, håndterer jobs->translate() pollingsløyfen for deg:

$done = $client->jobs->translate([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',
 
    // Valgfrie overstyringer (standardverdier vist):
    // 'pollInterval' => 5000,       // ms mellom polls, standard 5000
    // 'timeout'      => 1_200_000,  // total ventetid, standard 20 minutter
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);
 
$translations = $done['translations'];
$usage        = $done['usage'];

onProgress callback kalles ved hver poll med gjeldende køposisjon hvis API-et returnerer en, eller null hvis ikke tilgjengelig. Bruk den til å logge fremdrift eller oppdatere UI.

Verktøy-endepunkter

Tre lette endepunkter krever ingen parametere utover 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 og GET /languages krever ingen API-nøkkel. GET /usage returnerer tokenforbruk for inneværende kalendermåned for den autentiserte kontoen.

Feilhåndtering

Alle SDK-feil utvider PolyLingo\Errors\PolyLingoException. Fang de spesifikke undertypene du vil håndtere annerledes:

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 — ugyldig, manglende eller tilbakekalt API-nøkkel
} catch (RateLimitException $e) {
    // HTTP 429 — per-minutt grense nådd
    $retryAfter = $e->getRetryAfter(); // int|null sekunder
} catch (JobFailedException $e) {
    // Async jobb nådde en mislykket terminal status
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Alle andre API-feil
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // f.eks. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() returnerer antall sekunder å vente før du prøver igjen hvis API-et inkluderer den headeren, eller null hvis ikke tilstede. JobFailedException::getJobId() gir deg ID-en til den mislykkede jobben slik at du kan logge den eller vise den til brukeren.

Rask referanse

MetodeEndepunktAuth kreves
$client->health()GET /healthNei
$client->languages()GET /languagesNei
$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 i gang

SDK-en er på Packagist på usepolylingo/polylingo. Full API-dokumentasjon finnes på usepolylingo.com/docs.

Gratisnivået inkluderer 50 000 tokens per måned. Ingen kredittkort kreves.

composer require usepolylingo/polylingo

Få API-nøkkelen din