ترجمه محتوای ساختاریافته از 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 اگر در دسترس نباشد. از آن برای ثبت پیشرفت یا به‌روزرسانی رابط کاربری استفاده کنید.

نقاط پایانی کمکی

سه نقطه پایانی سبک نیاز به پارامتر فراتر از احراز هویت ندارند:

$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() شناسه کار شکست خورده را می‌دهد تا بتوانید آن را ثبت یا به کاربر نمایش دهید.

مرجع سریع

متد	نقطه پایانی	نیاز به احراز هویت
`$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 قرار دارد.

سطح رایگان شامل ۵۰٬۰۰۰ توکن در ماه است. نیاز به کارت اعتباری نیست.

composer require usepolylingo/polylingo

کلید API خود را دریافت کنید