Käännä jäsennelty sisältö PHP:stä PolyLingo SDK:lla

PolyLingo PHP SDK on nyt saatavilla Packagistissa. Asenna se Composerilla, anna sille tavallista tekstiä, Markdownia, JSONia tai HTML:ää sisältävä merkkijono, ja saat käännökset kaikilla tarvitsemillasi kielillä — ilman raakaa HTTP-koodin kirjoittamista tai huolta rakenteen rikkoutumisesta siirron aikana.

Tämä artikkeli kattaa asennuksen, todennuksen ja SDK:n koko käyttöliittymän: synkronisen käännöksen, eräpyynnöt, asynkroniset työt ja virheenkäsittelyn.

Asennus

Vaatii PHP 7.4 tai uudemman. Asenna Composerilla:

composer require usepolylingo/polylingo

SDK riippuu guzzlehttp/guzzle ^7.8 ja psr/http-client ^1.0 -kirjastoista. Molemmat asennetaan automaattisesti.

Asiakkaan määrittäminen

Luo yksi PolyLingo-instanssi ja käytä sitä sovelluksessasi uudelleen. Ainoa pakollinen asetus on API-avain:

<?php
use PolyLingo\PolyLingo;

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

Tallenna API-avaimesi ympäristömuuttujaan. Älä koskaan kovakoodaa sitä tai tallenna versionhallintaan.

Kaksi valinnaista asetusta, jotka kannattaa tietää:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // oletus, korvaa itse isännöidyissä instansseissa
    'timeout' => 120_000,                           // millisekunteina, oletus on 120000 (2 minuuttia)
]);

Sisällön kääntäminen

Tavallinen teksti, Markdown, JSON tai HTML

Anna sisältösi ja kohdekielikoodien taulukko translate()-metodille. format-kenttä kertoo SDK:lle, minkä tyyppistä sisältöä käsitellään:

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

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

format-vaihtoehto hyväksyy arvot plain, markdown, json tai html. Jos jätät sen pois, API tunnistaa muodon automaattisesti sisällöstä. Voit myös antaa source-kielivinkin ja model-arvon standard (oletus) tai advanced.

Muodon säilyttäminen on keskeinen ominaisuus. json-sisällössä vain merkkijonoarvot käännetään. Avaimet, sisäkkäisyys, taulukot ja ei-merkkijonotyypit palautuvat täsmälleen sellaisina kuin lähetit. Markdownissa otsikot pysyvät otsikoina, koodilohkot säilytetään sellaisenaan, eikä linkkien URL-osoitteita muuteta. HTML:ssä tagit ja attribuutit säilyvät, ja vain tekstisolmut käännetään.

JSON-lokalisointitiedoston kääntäminen

Yleinen käyttötapaus on lokalisointitiedoston kääntäminen. Lähetä koko objekti JSON-merkkijonona:

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

Yksi pyyntö käsittelee kaikki kolme lokalisointia. Avaimet pysyvät muuttumattomina kaikissa tulostetiedostoissa.

Eräpyynnöt

Käytä batch()-metodia, kun sinulla on useita erillisiä sisältökohteita käännettäväksi. Voit lähettää enintään 100 kohdetta yhdessä pyynnössä, jokaisella oma id ja valinnainen 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";
}

Kaikilla kohteilla on sama targets-taulukko. Vastaus säilyttää jokaisen kohteen lähettämäsi id:n, joten voit yhdistää tulokset alkuperäisiin tietoihisi ilman, että sinun tarvitsee luottaa järjestykseen.

Asynkroniset työt

Pitkään kestävissä käännöksissä (suuret dokumentit, monta kohdekieltä tai molemmat) jobs-API hyväksyy pyynnön, palauttaa heti job_id:n ja antaa sinun kysyä tulosta. SDK hoitaa tämän kahdella tavalla.

Laita jonoon ja kysy manuaalisesti

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

$jobId = $accepted['job_id'];

// Kysy tilaa, kunnes työ saavuttaa lopullisen tilan
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

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

Yksi kutsu, joka kysyy kunnes valmis

Jos et tarvitse manuaalista hallintaa, jobs->translate() hoitaa kyselysilmukan puolestasi:

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

    // Valinnaiset ylikirjoitukset (oletukset näytetty):
    // 'pollInterval' => 5000,       // ms kyselyjen välillä, oletus 5000
    // 'timeout'      => 1_200_000,  // kokonaisaika odotukselle, oletus 20 minuuttia
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Jonon paikka: {$queuePosition}\n";
    // },
]);

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

onProgress-takaisinkutsu laukeaa jokaisella kyselyllä nykyisellä jonopaikalla, jos API palauttaa sen, tai null jos ei ole saatavilla. Käytä sitä edistymisen kirjaamiseen tai käyttöliittymän päivittämiseen.

Apupisteet

Kolme kevyttä päätepistettä eivät tarvitse parametreja todennuksen lisäksi:

$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 ja GET /languages eivät vaadi API-avainta. GET /usage palauttaa tokenien kulutuksen kuluvan kalenterikuukauden ajalta todennetulle tilille.

Virheenkäsittely

Kaikki SDK:n virheet periytyvät PolyLingo\Errors\PolyLingoException-luokasta. Kiinniota haluamasi erityiset alityypit eri käsittelyä varten:

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 — virheellinen, puuttuva tai peruutettu API-avain
} catch (RateLimitException $e) {
    // HTTP 429 — minuuttikohtainen raja saavutettu
    $retryAfter = $e->getRetryAfter(); // int|null sekunteina
} catch (JobFailedException $e) {
    // Asynkroninen työ saavutti epäonnistuneen lopputilan
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Kaikki muut API-virheet
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // esim. "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() palauttaa sekuntimäärän, jonka jälkeen voi yrittää uudelleen, jos API sisältää kyseisen otsikon, tai null jos ei. JobFailedException::getJobId() antaa epäonnistuneen työn tunnuksen, jotta voit kirjata sen tai näyttää käyttäjälle.

Pikaviite

Metodi	Päätepiste	Tarvitseeko todennuksen
`$client->health()`	GET /health	Ei
`$client->languages()`	GET /languages	Ei
`$client->translate()`	POST /translate	Kyllä
`$client->batch()`	POST /translate/batch	Kyllä
`$client->usage()`	GET /usage	Kyllä
`$client->jobs->create()`	POST /jobs	Kyllä
`$client->jobs->get($id)`	GET /jobs/:id	Kyllä
`$client->jobs->translate()`	POST /jobs + kysely	Kyllä

Aloita

SDK on Packagistissa osoitteessa usepolylingo/polylingo. Täydellinen API-dokumentaatio löytyy osoitteesta usepolylingo.com/docs.

Ilmainen taso sisältää 50 000 tokenia kuukaudessa. Ei luottokorttia vaadita.

composer require usepolylingo/polylingo

Hanki API-avaimesi