Terjemahkan konten terstruktur dari PHP dengan PolyLingo SDK

PolyLingo PHP SDK sekarang tersedia di Packagist. Instal dengan Composer, berikan string teks biasa, Markdown, JSON, atau HTML, dan dapatkan terjemahan dalam setiap bahasa yang Anda butuhkan — tanpa menulis HTTP mentah atau khawatir struktur Anda rusak saat pengiriman.

Posting ini membahas instalasi, otentikasi, dan seluruh permukaan SDK: terjemahan sinkron, permintaan batch, pekerjaan async, dan penanganan kesalahan.

Instalasi

Memerlukan PHP 7.4 atau lebih baru. Instal melalui Composer:

composer require usepolylingo/polylingo

SDK bergantung pada guzzlehttp/guzzle ^7.8 dan psr/http-client ^1.0. Keduanya diambil secara otomatis.

Menyiapkan klien

Buat satu instance PolyLingo dan gunakan kembali di seluruh aplikasi Anda. Satu-satunya opsi yang diperlukan adalah kunci API Anda:

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

Simpan kunci API Anda dalam variabel lingkungan. Jangan pernah menuliskannya secara hardcode atau meng-commit ke kontrol versi.

Dua pengaturan opsional yang patut diketahui:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // default, ganti untuk instance self-hosted
    'timeout' => 120_000,                           // milidetik, default 120000 (2 menit)
]);

Menerjemahkan konten

Teks biasa, Markdown, JSON, atau HTML

Berikan konten Anda dan array kode bahasa target ke translate(). Field format memberi tahu SDK jenis konten apa yang sedang diproses:

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

Opsi format menerima plain, markdown, json, atau html. Jika Anda menghilangkannya, API akan mendeteksi format dari konten secara otomatis. Anda juga dapat memberikan petunjuk bahasa source dan nilai model standard (default) atau advanced.

Preservasi format adalah perilaku utama di sini. Untuk konten json, hanya nilai string yang diterjemahkan. Kunci, penempatan, array, dan tipe non-string kembali persis seperti yang Anda kirim. Untuk markdown, heading tetap heading, blok kode dibiarkan verbatim, dan URL tautan tidak disentuh. Untuk html, tag dan atribut dipertahankan dan hanya node teks yang diterjemahkan.

Menerjemahkan file locale JSON

Kasus penggunaan umum adalah menerjemahkan file locale. Kirim seluruh objek sebagai string 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 menangani ketiga locale. Kunci tidak disentuh di setiap file output.

Permintaan batch

Gunakan batch() saat Anda memiliki beberapa item konten terpisah untuk diterjemahkan. Anda dapat mengirim hingga 100 item dalam satu permintaan, masing-masing dengan id dan format opsional:

$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 berbagi array targets yang sama. Respons mempertahankan id yang Anda berikan untuk setiap item, sehingga Anda dapat memetakan hasil kembali ke data asli tanpa bergantung pada urutan.

Pekerjaan Async

Untuk terjemahan yang berjalan lama (dokumen besar, banyak target, atau keduanya) API pekerjaan menerima permintaan, mengembalikan segera dengan job_id, dan memungkinkan Anda polling untuk hasilnya. SDK menangani ini dengan dua cara.

Antri dan polling manual

$accepted = $client->jobs->create([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de', 'ja', 'zh'],
    'format'  => 'markdown',
]);
 
$jobId = $accepted['job_id'];
 
// Poll sampai pekerjaan 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 polling sampai selesai

Jika Anda tidak memerlukan kontrol manual, jobs->translate() menangani loop polling untuk Anda:

$done = $client->jobs->translate([
    'content' => file_get_contents('long-article.md'),
    'targets' => ['es', 'fr', 'de'],
    'format'  => 'markdown',
 
    // Override opsional (default ditampilkan):
    // 'pollInterval' => 5000,       // ms antar polling, default 5000
    // 'timeout'      => 1_200_000,  // total waktu tunggu, default 20 menit
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Posisi antrean: {$queuePosition}\n";
    // },
]);
 
$translations = $done['translations'];
$usage        = $done['usage'];

Callback onProgress dipanggil pada setiap polling dengan posisi antrean saat ini jika API mengembalikannya, atau null jika tidak tersedia. Gunakan untuk mencatat kemajuan atau memperbarui UI.

Endpoint utilitas

Tiga endpoint ringan tidak memerlukan parameter selain otentikasi:

$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 konsumsi token untuk bulan kalender saat ini untuk akun yang diautentikasi.

Penanganan kesalahan

Semua kesalahan SDK memperluas PolyLingo\Errors\PolyLingoException. Tangkap subtipe spesifik yang ingin Anda tangani secara berbeda:

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 valid, hilang, atau dicabut
} catch (RateLimitException $e) {
    // HTTP 429 — batas per menit tercapai
    $retryAfter = $e->getRetryAfter(); // int|null detik
} catch (JobFailedException $e) {
    // Pekerjaan async mencapai status terminal gagal
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Semua kesalahan API lainnya
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // misal "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() mengembalikan jumlah detik untuk menunggu sebelum mencoba lagi jika API menyertakan header tersebut, atau null jika tidak ada. JobFailedException::getJobId() memberi Anda ID pekerjaan yang gagal sehingga Anda dapat mencatatnya atau menampilkannya ke pengguna.

Referensi cepat

Metode	Endpoint	Memerlukan Auth
`$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 + polling	Ya

Mulai

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

Tingkat gratis mencakup 50.000 token per bulan. Tidak perlu kartu kredit.

composer require usepolylingo/polylingo

Dapatkan kunci API Anda