Terjemahkan kandungan berstruktur dari PHP dengan SDK PolyLingo

SDK PolyLingo PHP kini tersedia di Packagist. Pasang ia dengan Composer, berikan ia rentetan teks biasa, Markdown, JSON, atau HTML, dan dapatkan terjemahan dalam setiap bahasa yang anda perlukan — tanpa menulis HTTP mentah atau risau tentang struktur anda rosak semasa penghantaran.

Pos ini merangkumi pemasangan, pengesahan, dan keseluruhan permukaan SDK: terjemahan segerak, permintaan kumpulan, tugasan async, dan pengendalian ralat.

Pemasangan

Memerlukan PHP 7.4 atau lebih baru. Pasang melalui Composer:

composer require usepolylingo/polylingo

SDK bergantung pada guzzlehttp/guzzle ^7.8 dan psr/http-client ^1.0. Kedua-duanya dimuatkan secara automatik.

Menyediakan klien

Buat satu instans PolyLingo dan guna semula di seluruh aplikasi anda. Pilihan yang diperlukan hanyalah kunci API anda:

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

Simpan kunci API anda dalam pembolehubah persekitaran. Jangan sekali-kali kod keras atau komit ke kawalan versi.

Dua tetapan pilihan yang patut diketahui:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // lalai, ganti untuk instans sendiri
    'timeout' => 120_000,                           // milisaat, lalai ialah 120000 (2 minit)
]);

Menerjemah kandungan

Teks biasa, Markdown, JSON, atau HTML

Berikan kandungan anda dan tatasusunan kod bahasa sasaran ke translate(). Medan format memberitahu SDK jenis kandungan yang sedang diuruskan:

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

Pilihan format menerima plain, markdown, json, atau html. Jika anda tidak sertakan, API akan mengesan format secara automatik dari kandungan. Anda juga boleh berikan petunjuk bahasa source dan nilai model standard (lalai) atau advanced.

Pemeliharaan format adalah tingkah laku utama di sini. Untuk kandungan json, hanya nilai rentetan diterjemah. Kekunci, penjerutan, tatasusunan, dan jenis bukan rentetan dikembalikan tepat seperti yang anda hantar. Untuk markdown, tajuk kekal tajuk, blok kod dibiarkan secara verbatim, dan URL pautan tidak disentuh. Untuk html, tag dan atribut dipelihara dan hanya nod teks diterjemah.

Menerjemah fail locale JSON

Kes penggunaan biasa adalah menerjemah fail locale. Hantar keseluruhan objek sebagai rentetan 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"
    );
}

Satu permintaan mengendalikan ketiga-tiga locale. Kekunci tidak disentuh dalam setiap fail output.

Permintaan kumpulan

Gunakan batch() apabila anda mempunyai beberapa item kandungan berasingan untuk diterjemah. Anda boleh hantar sehingga 100 item dalam satu permintaan, setiap satu dengan id sendiri dan format pilihan:

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

Semua item berkongsi tatasusunan targets yang sama. Respons memelihara id yang anda berikan untuk setiap item, jadi anda boleh memetakan keputusan kembali ke data asal tanpa bergantung pada susunan.

Tugasan Async

Untuk terjemahan yang berjalan lama (dokumen besar, banyak sasaran, atau kedua-duanya) API tugasan menerima permintaan, kembali segera dengan job_id, dan membolehkan anda memeriksa hasil. SDK mengendalikan ini dengan dua cara.

Antri dan periksa secara manual

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

Satu panggilan yang memeriksa sehingga selesai

Jika anda tidak memerlukan kawalan manual, jobs->translate() mengendalikan gelung pemeriksaan untuk anda:

$done = $client->jobs->translate([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',
 
    // Gantian pilihan (lalai ditunjukkan):
    // 'pollInterval' => 5000,       // ms antara pemeriksaan, lalai 5000
    // 'timeout'      => 1_200_000,  // bajet menunggu total, lalai 20 minit
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);
 
$translations = $done['translations'];
$usage        = $done['usage'];

Panggilan balik onProgress dipanggil pada setiap pemeriksaan dengan posisi antrian semasa jika API mengembalikannya, atau null jika tidak tersedia. Gunakan ia untuk merekod kemajuan atau mengemas kini UI.

Titik akhir utiliti

Tiga titik akhir ringan tidak memerlukan parameter selain pengesahan:

$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 dan GET /languages tidak memerlukan kunci API. GET /usage mengembalikan penggunaan token untuk bulan kalendar semasa bagi akaun yang disahkan.

Pengendalian ralat

Semua ralat SDK mewarisi PolyLingo\Errors\PolyLingoException. Tangkap subjenis khusus yang anda mahu kendalikan secara berbeza:

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 — kunci API tidak sah, hilang, atau dibatalkan
} catch (RateLimitException $e) {
    // HTTP 429 — had per minit dicapai
    $retryAfter = $e->getRetryAfter(); // int|null saat
} catch (JobFailedException $e) {
    // Tugasan async mencapai status terminal gagal
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Semua ralat API lain
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // contohnya "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() mengembalikan bilangan saat untuk menunggu sebelum mencuba semula jika API menyertakan header itu, atau null jika tidak ada. JobFailedException::getJobId() memberikan ID tugasan yang gagal supaya anda boleh merekod atau memaparkannya kepada pengguna.

Rujukan pantas

Kaedah	Titik akhir	Perlu pengesahan
`$client->health()`	GET /health	Tidak
`$client->languages()`	GET /languages	Tidak
`$client->translate()`	POST /translate	Ya
`$client->batch()`	POST /translate/batch	Ya
`$client->usage()`	GET /usage	Ya
`$client->jobs->create()`	POST /jobs	Ya
`$client->jobs->get($id)`	GET /jobs/:id	Ya
`$client->jobs->translate()`	POST /jobs + pemeriksaan	Ya

Mula

SDK ada di Packagist di usepolylingo/polylingo. Dokumentasi API penuh ada di usepolylingo.com/docs.

Tier percuma termasuk 50,000 token sebulan. Tiada kad kredit diperlukan.

composer require usepolylingo/polylingo

Dapatkan kunci API anda

Terjemahkan kandungan berstruktur dari PHP dengan PolyLingo SDK