← Quay lại blog
Terminal window showing a Composer install command for the PolyLingo PHP SDK alongside a short PHP translate call and its JSON output.

Dịch nội dung có cấu trúc từ PHP với PolyLingo SDK

By Robert M

Dịch nội dung có cấu trúc từ PHP với PolyLingo SDK

PolyLingo PHP SDK hiện đã có trên Packagist. Cài đặt nó bằng Composer, truyền vào một chuỗi văn bản thuần túy, Markdown, JSON hoặc HTML, và nhận lại bản dịch ở mọi ngôn ngữ bạn cần — mà không phải viết HTTP thô hoặc lo lắng về việc cấu trúc của bạn bị hỏng trong quá trình truyền.

Bài viết này bao gồm cài đặt, xác thực và toàn bộ tính năng của SDK: dịch đồng bộ, yêu cầu theo lô, công việc bất đồng bộ và xử lý lỗi.

Cài đặt

Yêu cầu PHP 7.4 trở lên. Cài đặt qua Composer:

composer require usepolylingo/polylingo

SDK phụ thuộc vào guzzlehttp/guzzle ^7.8 và psr/http-client ^1.0. Cả hai sẽ được tự động tải về.

Thiết lập client

Tạo một thể hiện PolyLingo duy nhất và tái sử dụng nó trong toàn bộ ứng dụng của bạn. Tùy chọn duy nhất bắt buộc là khóa API của bạn:

<?php
use PolyLingo\PolyLingo;

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

Lưu khóa API của bạn trong biến môi trường. Không bao giờ mã hóa cứng hoặc commit vào hệ thống kiểm soát phiên bản.

Hai cài đặt tùy chọn đáng biết:

$client = new PolyLingo([
    'apiKey'  => getenv('POLYLINGO_API_KEY'),
    'baseURL' => 'https://api.usepolylingo.com/v1', // mặc định, ghi đè cho các instance tự lưu trữ
    'timeout' => 120_000,                           // mili giây, mặc định là 120000 (2 phút)
]);

Dịch nội dung

Văn bản thuần túy, Markdown, JSON hoặc HTML

Truyền nội dung và một mảng mã ngôn ngữ đích vào translate(). Trường format cho SDK biết loại nội dung đang xử lý:

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

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

Tùy chọn format chấp nhận plain, markdown, json hoặc html. Nếu bạn bỏ qua, API sẽ tự động phát hiện định dạng từ nội dung. Bạn cũng có thể truyền gợi ý ngôn ngữ nguồn source và giá trị model là standard (mặc định) hoặc advanced.

Bảo toàn định dạng là hành vi chính ở đây. Với nội dung json, chỉ các giá trị chuỗi được dịch. Khóa, cấu trúc lồng nhau, mảng và các kiểu không phải chuỗi được trả về chính xác như bạn gửi. Với markdown, các tiêu đề vẫn là tiêu đề, khối mã giữ nguyên, và URL liên kết không bị thay đổi. Với html, thẻ và thuộc tính được giữ nguyên và chỉ các nút văn bản được dịch.

Dịch tệp locale JSON

Một trường hợp sử dụng phổ biến là dịch tệp locale. Gửi toàn bộ đối tượng dưới dạng chuỗi 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"
    );
}

Một yêu cầu xử lý cả ba locale. Khóa không bị thay đổi trong mọi tệp đầu ra.

Yêu cầu theo lô

Sử dụng batch() khi bạn có nhiều mục nội dung riêng biệt cần dịch. Bạn có thể gửi tối đa 100 mục trong một yêu cầu, mỗi mục có id riêng và format tùy chọn:

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

Tất cả các mục chia sẻ cùng một mảng targets. Phản hồi giữ lại id bạn đã gửi cho mỗi mục, để bạn có thể ánh xạ kết quả trở lại dữ liệu gốc mà không phụ thuộc vào thứ tự.

Công việc bất đồng bộ

Đối với các bản dịch chạy lâu (tài liệu lớn, nhiều mục tiêu hoặc cả hai), API công việc nhận yêu cầu, trả về ngay với job_id, và cho phép bạn kiểm tra kết quả. SDK xử lý điều này theo hai cách.

Đưa vào hàng đợi và kiểm tra thủ công

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

$jobId = $accepted['job_id'];

// Kiểm tra cho đến khi công việc đạt trạng thái cuối cùng
do {
    sleep(5);
    $state = $client->jobs->get($jobId);
} while ($state['status'] === 'pending' || $state['status'] === 'processing');

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

Một lần gọi kiểm tra cho đến khi xong

Nếu bạn không cần kiểm soát thủ công, jobs->translate() sẽ xử lý vòng kiểm tra cho bạn:

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

    // Ghi đè tùy chọn (hiển thị mặc định):
    // 'pollInterval' => 5000,       // ms giữa các lần kiểm tra, mặc định 5000
    // 'timeout'      => 1_200_000,  // tổng thời gian chờ, mặc định 20 phút
    // 'onProgress'   => function (?int $queuePosition) {
    //     echo "Queue position: {$queuePosition}\n";
    // },
]);

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

Hàm gọi lại onProgress được kích hoạt ở mỗi lần kiểm tra với vị trí hàng đợi hiện tại nếu API trả về, hoặc null nếu không có. Dùng để ghi lại tiến trình hoặc cập nhật giao diện người dùng.

Các điểm cuối tiện ích

Ba điểm cuối nhẹ không cần tham số ngoài xác thực:

$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 và GET /languages không yêu cầu khóa API. GET /usage trả về mức tiêu thụ token trong tháng hiện tại cho tài khoản đã xác thực.

Xử lý lỗi

Tất cả lỗi SDK mở rộng từ PolyLingo\Errors\PolyLingoException. Bắt các loại con cụ thể bạn muốn xử lý khác nhau:

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 — khóa API không hợp lệ, thiếu hoặc bị thu hồi
} catch (RateLimitException $e) {
    // HTTP 429 — đạt giới hạn theo phút
    $retryAfter = $e->getRetryAfter(); // int|null giây
} catch (JobFailedException $e) {
    // Công việc bất đồng bộ đạt trạng thái lỗi
    $jobId = $e->getJobId();
} catch (PolyLingoException $e) {
    // Tất cả lỗi API khác
    $httpStatus = $e->getHttpStatus();
    $errorCode  = $e->getErrorCode(); // ví dụ "invalid_request", "translation_error"
}

RateLimitException::getRetryAfter() trả về số giây cần chờ trước khi thử lại nếu API có header đó, hoặc null nếu không có. JobFailedException::getJobId() cung cấp ID công việc thất bại để bạn có thể ghi lại hoặc hiển thị cho người dùng.

Tham khảo nhanh

Phương thứcĐiểm cuốiCần xác thực
$client->health()GET /healthKhông
$client->languages()GET /languagesKhông
$client->translate()POST /translateCó
$client->batch()POST /translate/batchCó
$client->usage()GET /usageCó
$client->jobs->create()POST /jobsCó
$client->jobs->get($id)GET /jobs/:idCó
$client->jobs->translate()POST /jobs + pollingCó

Bắt đầu

SDK có trên Packagist tại usepolylingo/polylingo. Tài liệu API đầy đủ tại usepolylingo.com/docs.

Gói miễn phí bao gồm 50.000 token mỗi tháng. Không cần thẻ tín dụng.

composer require usepolylingo/polylingo

Nhận khóa API của bạn