← กลับไปที่บล็อก
Terminal window showing a Composer install command for the PolyLingo PHP SDK alongside a short PHP translate call and its JSON output.

แปลเนื้อหาที่มีโครงสร้างจาก PHP ด้วย PolyLingo SDK

By Robert M

แปลเนื้อหาที่มีโครงสร้างจาก PHP ด้วย PolyLingo SDK

PolyLingo PHP SDK พร้อมใช้งานบน Packagist แล้ว ติดตั้งด้วย Composer ส่งข้อความธรรมดา Markdown JSON หรือ HTML ให้ แล้วรับการแปลในทุกภาษาที่คุณต้องการ — โดยไม่ต้องเขียน HTTP ดิบหรือกังวลว่าโครงสร้างของคุณจะเสียหายในระหว่างทาง

โพสต์นี้ครอบคลุมการติดตั้ง การตรวจสอบสิทธิ์ และฟีเจอร์ทั้งหมดของ SDK: การแปลแบบซิงโครนัส คำขอแบบกลุ่ม งานแบบอะซิงโครนัส และการจัดการข้อผิดพลาด

การติดตั้ง

ต้องใช้ PHP 7.4 หรือใหม่กว่า ติดตั้งผ่าน Composer:

composer require usepolylingo/polylingo

SDK ต้องการ guzzlehttp/guzzle ^7.8 และ psr/http-client ^1.0 ทั้งสองจะถูกดึงมาโดยอัตโนมัติ

การตั้งค่าลูกค้า

สร้างอินสแตนซ์ PolyLingo เพียงตัวเดียวและใช้ซ้ำทั่วแอปพลิเคชันของคุณ ตัวเลือกที่จำเป็นเพียงอย่างเดียวคือคีย์ API ของคุณ:

<?php
use PolyLingo\PolyLingo;

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

เก็บคีย์ API ของคุณในตัวแปรสภาพแวดล้อม อย่ารหัสคีย์ไว้ในโค้ดหรือคอมมิตลงในระบบควบคุมเวอร์ชัน

มีการตั้งค่าเสริมสองอย่างที่ควรรู้:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // ค่าเริ่มต้น, เปลี่ยนสำหรับอินสแตนซ์ที่โฮสต์เอง
    'timeout' => 120_000,                           // มิลลิวินาที, ค่าเริ่มต้นคือ 120000 (2 นาที)
]);

การแปลเนื้อหา

ข้อความธรรมดา Markdown JSON หรือ HTML

ส่งเนื้อหาและอาร์เรย์ของรหัสภาษาปลายทางไปยัง translate() ฟิลด์ format บอก SDK ว่ากำลังจัดการกับเนื้อหาประเภทใด:

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

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

ตัวเลือก format รับค่า plain, markdown, json, หรือ html หากไม่ระบุ API จะตรวจจับรูปแบบจากเนื้อหาโดยอัตโนมัติ คุณยังสามารถส่งคำใบ้ภาษาต้นทาง source และค่ารุ่น model เป็น standard (ค่าเริ่มต้น) หรือ advanced

การรักษารูปแบบเป็นพฤติกรรมสำคัญ สำหรับเนื้อหา json จะแปลเฉพาะค่าที่เป็นสตริงเท่านั้น คีย์ การซ้อน อาร์เรย์ และชนิดข้อมูลที่ไม่ใช่สตริงจะถูกส่งกลับเหมือนที่คุณส่งไป สำหรับ markdown หัวข้อยังคงเป็นหัวข้อ บล็อกโค้ดยังคงเหมือนเดิม และ URL ของลิงก์จะไม่ถูกแตะต้อง สำหรับ html แท็กและแอตทริบิวต์จะถูกเก็บไว้และแปลเฉพาะโหนดข้อความ

การแปลไฟล์ locale JSON

กรณีใช้งานทั่วไปคือการแปลไฟล์ locale ส่งอ็อบเจ็กต์ทั้งหมดเป็นสตริง 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"
    );
}

คำขอเดียวจัดการ locale ทั้งสาม คีย์ไม่ถูกแตะต้องในทุกไฟล์ผลลัพธ์

คำขอแบบกลุ่ม

ใช้ batch() เมื่อคุณมีหลายรายการเนื้อหาแยกกันให้แปล คุณสามารถส่งได้สูงสุด 100 รายการในคำขอเดียว แต่ละรายการมี id ของตัวเองและ 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";
}

รายการทั้งหมดใช้ targets เดียวกัน การตอบสนองเก็บ id ที่คุณส่งมาในแต่ละรายการไว้ เพื่อให้คุณแมปผลลัพธ์กลับไปยังข้อมูลต้นฉบับโดยไม่ต้องพึ่งลำดับ

งานแบบอะซิงโครนัส

สำหรับการแปลที่ใช้เวลานาน (เอกสารขนาดใหญ่ หลายเป้าหมาย หรือทั้งสองอย่าง) API งานรับคำขอ ส่งกลับทันทีพร้อม job_id และให้คุณตรวจสอบผลลัพธ์ได้ SDK จัดการสิ่งนี้สองวิธี

เข้าคิวและตรวจสอบด้วยตนเอง

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

$jobId = $accepted['job_id'];

// ตรวจสอบจนกว่างานจะถึงสถานะสิ้นสุด
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

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

การเรียกครั้งเดียวที่ตรวจสอบจนเสร็จ

ถ้าคุณไม่ต้องการควบคุมด้วยตนเอง jobs->translate() จะจัดการลูปการตรวจสอบให้:

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

    // ตัวเลือกเสริม (แสดงค่าเริ่มต้น):
    // 'pollInterval' => 5000,       // มิลลิวินาทีระหว่างการตรวจสอบ, ค่าเริ่มต้น 5000
    // 'timeout'      => 1_200_000,  // งบประมาณเวลารวม, ค่าเริ่มต้น 20 นาที
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);

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

คอลแบ็ก onProgress จะถูกเรียกในแต่ละการตรวจสอบพร้อมตำแหน่งคิวปัจจุบันถ้า API ส่งมา หรือ null ถ้าไม่มี ใช้เพื่อล็อกความคืบหน้าหรืออัปเดต UI

จุดสิ้นสุดยูทิลิตี้

สามจุดสิ้นสุดน้ำหนักเบาไม่ต้องการพารามิเตอร์นอกจากการตรวจสอบสิทธิ์:

$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 และ GET /languages ไม่ต้องใช้คีย์ API GET /usage คืนค่าการใช้โทเค็นของเดือนปฏิทินปัจจุบันสำหรับบัญชีที่ตรวจสอบสิทธิ์แล้ว

การจัดการข้อผิดพลาด

ข้อผิดพลาดทั้งหมดของ SDK ขยายจาก PolyLingo\Errors\PolyLingoException จับชนิดย่อยเฉพาะที่คุณต้องการจัดการแตกต่างกัน:

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 — คีย์ API ไม่ถูกต้อง ขาด หรือถูกเพิกถอน
} catch (RateLimitException $e) {
    // HTTP 429 — ถึงขีดจำกัดต่อนาที
    $retryAfter = $e->getRetryAfter(); // int|null วินาที
} catch (JobFailedException $e) {
    // งานอะซิงโครนัสถึงสถานะล้มเหลว
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // ข้อผิดพลาด API อื่น ๆ ทั้งหมด
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // เช่น "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() คืนจำนวนวินาทีที่ต้องรอก่อนลองใหม่ถ้า API มีหัวข้อนั้น หรือ null ถ้าไม่มี JobFailedException::getJobId() ให้ ID ของงานที่ล้มเหลวเพื่อให้คุณบันทึกหรือแสดงให้ผู้ใช้เห็น

อ้างอิงด่วน

วิธีการจุดสิ้นสุดต้องตรวจสอบสิทธิ์
$client->health()GET /healthไม่
$client->languages()GET /languagesไม่
$client->translate()POST /translateใช่
$client->batch()POST /translate/batchใช่
$client->usage()GET /usageใช่
$client->jobs->create()POST /jobsใช่
$client->jobs->get($id)GET /jobs/:idใช่
$client->jobs->translate()POST /jobs + pollingใช่

เริ่มต้น

SDK อยู่บน Packagist ที่ usepolylingo/polylingo เอกสาร API เต็มรูปแบบที่ usepolylingo.com/docs

ระดับฟรีรวม 50,000 โทเค็นต่อเดือน ไม่ต้องใช้บัตรเครดิต

composer require usepolylingo/polylingo

รับคีย์ API ของคุณ