Tafsiri ya maudhui yaliyopangwa kutoka PHP kwa kutumia PolyLingo SDK

PolyLingo PHP SDK sasa inapatikana kwenye Packagist. Iweke kwa kutumia Composer, mpe mfuatano wa maandishi ya kawaida, Markdown, JSON, au HTML, na upate tafsiri kwa kila lugha unayohitaji — bila kuandika HTTP ghafi au kuhofia muundo wako kuharibika wakati wa usafirishaji.

Chapisho hili linahusu usakinishaji, uthibitishaji, na matumizi yote ya SDK: tafsiri ya wakati mmoja, maombi ya kundi, kazi zisizo za wakati mmoja, na usimamizi wa makosa.

Usakinishaji

Inahitaji PHP 7.4 au baadaye. Sakinisha kupitia Composer:

composer require usepolylingo/polylingo

SDK inategemea guzzlehttp/guzzle ^7.8 na psr/http-client ^1.0. Zote zinapakuliwa moja kwa moja.

Kuweka mteja

Tengeneza mfano mmoja wa PolyLingo na utumie tena katika programu yako yote. Chaguo pekee linalohitajika ni ufunguo wako wa API:

<?php
use PolyLingo\PolyLingo;

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

Hifadhi ufunguo wako wa API katika mabadiliko ya mazingira. Usihifadhi moja kwa moja au kuingiza kwenye udhibiti wa toleo.

Mipangilio miwili ya hiari inayostahili kujua:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // chaguo-msingi, badilisha kwa mifumo inayojimiliki
    'timeout' => 120_000,                           // millisekunde, chaguo-msingi ni 120000 (dakika 2)
]);

Kutafsiri maudhui

Maandishi ya kawaida, Markdown, JSON, au HTML

Pitia maudhui yako na safu ya misimbo ya lugha lengwa kwa translate(). Sehemu ya format inaambia SDK aina gani ya maudhui inashughulikiwa:

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

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

Chaguo la format linakubali plain, markdown, json, au html. Ukikosa, API hutambua moja kwa moja muundo kutoka kwa maudhui. Pia unaweza kutoa kidokezo cha lugha ya source na thamani ya model ya standard (chaguo-msingi) au advanced.

Uhifadhi wa muundo ndio tabia kuu hapa. Kwa maudhui ya json, thamani za maandishi pekee ndizo zinazotafsiriwa. Funguo, uingizaji, orodha, na aina zisizo za maandishi hurudi kama ulizotuma. Kwa markdown, vichwa vinabaki vichwa, sehemu za msimbo hazibadiliki, na URL za viungo hazigusiwi. Kwa html, lebo na sifa zinahifadhiwa na nodi za maandishi pekee ndizo zinazotafsiriwa.

Kutafsiri faili la eneo la JSON

Matumizi ya kawaida ni kutafsiri faili la eneo. Tuma kitu kizima kama mfuatano wa JSON:

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

Ombi moja hushughulikia maeneo yote matatu. Funguo hazibadiliki katika kila faili ya matokeo.

Maombi ya kundi

Tumia batch() unapokuwa na vitu vingi tofauti vya maudhui kutafsiri. Unaweza kutuma hadi vitu 100 katika ombi moja, kila moja ikiwa na id yake na format hiari:

$batch = $client->batch([
    'items' => [
        ['id' => 'hero_title',    'content' => 'Karibu tena',              'format' => 'plain'],
        ['id' => 'hero_subtitle', 'content' => 'Hapa ni kile kipya leo', 'format' => 'plain'],
        ['id' => 'cta',           'content' => 'Anza sasa',               'format' => 'plain'],
    ],
    'targets' => ['es', 'fr'],
]);

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

Vitu vyote vinashiriki safu moja ya targets. Jibu linahifadhi id uliyotuma kwa kila kipengee, ili uweze kurudisha matokeo kwa data yako ya awali bila kutegemea mpangilio.

Kazi zisizo za wakati mmoja

Kwa tafsiri za muda mrefu (nyaraka kubwa, malengo mengi, au yote mawili) API ya kazi inakubali ombi, inarudisha mara moja job_id, na inakuwezesha kuangalia matokeo. SDK inashughulikia hili kwa njia mbili.

Weka kwenye foleni na angalia kwa mkono

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

$jobId = $accepted['job_id'];

// Angalia hadi kazi ifikie hali ya mwisho
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

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

Mwito mmoja unaoangalia hadi ukamilike

Kama huna haja ya udhibiti wa mkono, jobs->translate() inasimamia mzunguko wa kuangalia kwa niaba yako:

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

    // Mabadiliko ya hiari (chaguo-msingi yanaonyeshwa):
    // 'pollInterval' => 5000,       // ms kati ya kuangalia, chaguo-msingi 5000
    // 'timeout'      => 1_200_000,  // muda wa kusubiri jumla, chaguo-msingi dakika 20
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Nafasi foleni: {$queuePosition}\n";
    // },
]);

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

Callback ya onProgress huanzishwa kila mara ya kuangalia na nafasi ya sasa foleni ikiwa API inarudisha moja, au null ikiwa haipatikani. Tumia kuandika maendeleo au kusasisha UI.

Vituo vya huduma

Vituo vitatu vyepesi havihitaji vigezo zaidi ya uthibitishaji:

$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 na GET /languages hazihitaji ufunguo wa API. GET /usage hurudisha matumizi ya tokeni kwa mwezi wa kalenda wa sasa kwa akaunti iliyothibitishwa.

Usimamizi wa makosa

Makosa yote ya SDK yanapanuliwa kutoka PolyLingo\Errors\PolyLingoException. Kamata aina ndogo unazotaka kushughulikia tofauti:

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

try {
    $result = $client->translate([
        'content' => '# Habari',
        'targets' => ['es'],
        'format'  => 'markdown',
    ]);
} catch (AuthException $e) {
    // HTTP 401 — ufunguo wa API batili, umekosekana, au umefutwa
} catch (RateLimitException $e) {
    // HTTP 429 — kikomo cha dakika kimefikiwa
    $retryAfter = $e->getRetryAfter(); // int|null sekunde
} catch (JobFailedException $e) {
    // Kazi isiyo ya wakati mmoja imefikia hali ya mwisho ya kushindwa
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Makosa mengine yote ya API
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // mfano "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() hurudisha idadi ya sekunde za kusubiri kabla ya kujaribu tena ikiwa API inajumuisha kichwa hicho, au null ikiwa hakipo. JobFailedException::getJobId() inakupa ID ya kazi iliyoshindwa ili uweze kuiandika au kuionyesha mtumiaji.

Marejeleo ya haraka

Mbinu	Endpoint	Inahitaji uthibitishaji
`$client->health()`	GET /health	Hapana
`$client->languages()`	GET /languages	Hapana
`$client->translate()`	POST /translate	Ndiyo
`$client->batch()`	POST /translate/batch	Ndiyo
`$client->usage()`	GET /usage	Ndiyo
`$client->jobs->create()`	POST /jobs	Ndiyo
`$client->jobs->get($id)`	GET /jobs/:id	Ndiyo
`$client->jobs->translate()`	POST /jobs + polling	Ndiyo

Anza sasa

SDK iko kwenye Packagist kwenye usepolylingo/polylingo. Nyaraka kamili za API ziko kwenye usepolylingo.com/docs.

Ngazi ya bure inajumuisha tokeni 50,000 kwa mwezi. Hakuna kadi ya mkopo inahitajika.

composer require usepolylingo/polylingo

Pata ufunguo wako wa API

Tafsiri maudhui yaliyopangwa kutoka PHP kwa kutumia PolyLingo SDK