Oversæt struktureret indhold fra PHP med PolyLingo SDK

PolyLingo PHP SDK er nu tilgængelig på Packagist. Installer det med Composer, giv det en streng med almindelig tekst, Markdown, JSON eller HTML, og få oversættelser tilbage på alle de sprog, du har brug for — uden at skrive rå HTTP eller bekymre dig om, at din struktur bliver ødelagt undervejs.

Dette indlæg dækker installation, autentificering og hele SDK'ens funktionalitet: synkron oversættelse, batch-forespørgsler, asynkrone jobs og fejlhåndtering.

---

Installation

Kræver PHP 7.4 eller nyere. Installer via Composer:

composer require usepolylingo/polylingo

SDK afhænger af guzzlehttp/guzzle ^7.8 og psr/http-client ^1.0. Begge hentes automatisk.

---

Opsætning af klienten

Opret en enkelt PolyLingo-instans og genbrug den i hele din applikation. Den eneste nødvendige mulighed er din API-nøgle:

<?php
use PolyLingo\PolyLingo;

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

Gem din API-nøgle i en miljøvariabel. Hardkod den aldrig eller commit den til versionskontrol.

To valgfrie indstillinger, som er værd at kende til:

$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)
]);

---

Oversættelse af indhold

Almindelig tekst, Markdown, JSON eller HTML

Send dit indhold og et array med mål-sprogkoder til translate(). Feltet format fortæller SDK, hvilken slags indhold det arbejder med:

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

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

format-muligheden accepterer plain, markdown, json eller html. Hvis du udelader den, registrerer API'et formatet automatisk ud fra indholdet. Du kan også sende et source-sprogstip og en model-værdi på standard (standard) eller advanced.

Bevarelse af format er den vigtigste funktion her. For json-indhold oversættes kun strengværdier. Nøgler, indlejring, arrays og ikke-streng-typer returneres præcis som du sendte dem. For markdown forbliver overskrifter overskrifter, kodeblokke efterlades uændrede, og link-URL'er berøres ikke. For html bevares tags og attributter, og kun tekstnoder oversættes.

Oversættelse af en JSON-lokalfils

Et almindeligt brugsscenarie er at oversætte en lokalefil. 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ørgsel håndterer alle tre lokaliteter. Nøgler berøres ikke i nogen outputfil.

---

Batch-forespørgsler

Brug batch(), når du har flere separate indholdselementer, der skal oversættes. Du kan sende op til 100 elementer i en enkelt forespørgsel, hver med sit eget id og valgfrit 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 det samme targets-array. Svaret bevarer det id, du sendte for hvert element, så du kan matche resultaterne tilbage til dine originale data uden at stole på rækkefølgen.

---

Asynkrone jobs

For langvarige oversættelser (store dokumenter, mange mål eller begge dele) accepterer jobs-API'et en forespørgsel, returnerer straks et job_id og lader dig poll'e efter resultatet. SDK håndterer dette på to måder.

Sæt 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 indtil jobbet 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'];
}

Ét kald, der poller indtil færdigt

Hvis du ikke har brug for manuel kontrol, håndterer jobs->translate() polling-løkken for dig:

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

    // Valgfrie overskrivninger (standarder vist):
    // 'pollInterval' => 5000,       // ms mellem polls, standard 5000
    // 'timeout'      => 1_200_000,  // samlet ventetid, standard 20 minutter
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);

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

onProgress callback'en affyres ved hver poll med den aktuelle køposition, hvis API'et returnerer en, ellers null. Brug den til at logge fremskridt eller opdatere et UI.

---

Hjælpeendepunkter

Tre lette endepunkter kræver ingen parametre ud over autentificering:

$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 kræver ikke API-nøgle. GET /usage returnerer tokenforbrug for den aktuelle kalender måned for den autentificerede konto.

---

Fejlhåndtering

Alle SDK-fejl udvider PolyLingo\Errors\PolyLingoException. Fang de specifikke undertyper, du vil håndtere forskelligt:

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 tilbagekaldt API-nøgle
} catch (RateLimitException $e) {
    // HTTP 429 — minutgrænse nået
    $retryAfter = $e->getRetryAfter(); // int|null sekunder
} catch (JobFailedException $e) {
    // Asynkront job nåede en fejlet terminal status
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Alle andre API-fejl
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // f.eks. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() returnerer antallet af sekunder, der skal ventes før genforsøg, hvis API'et inkluderer denne header, ellers null. JobFailedException::getJobId() giver dig ID'et på det fejlede job, så du kan logge det eller vise det til brugeren.

---

Hurtig reference

Metode	Endepunkt	Auth påkrævet
$client->health()	GET /health	Nej
$client->languages()	GET /languages	Nej
$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

---

Kom i gang

SDK er på Packagist på usepolylingo/polylingo. Fuld API-dokumentation findes på usepolylingo.com/docs.

Gratis niveau inkluderer 50.000 tokens pr. måned. Ingen kreditkort kræves.

composer require usepolylingo/polylingo

Få din API-nøgle