← ব্লগে ফিরে যান
Terminal window showing a Composer install command for the PolyLingo PHP SDK alongside a short PHP translate call and its JSON output.

PolyLingo SDK দিয়ে PHP থেকে কাঠামোবদ্ধ সামগ্রী অনুবাদ করুন

By Robert M

PolyLingo SDK দিয়ে PHP থেকে কাঠামোবদ্ধ কনটেন্ট অনুবাদ করুন

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 (২ মিনিট)
]);

কনটেন্ট অনুবাদ

সাধারণ টেক্সট, 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 এর জন্য, ট্যাগ এবং অ্যাট্রিবিউট সংরক্ষিত থাকে এবং শুধুমাত্র টেক্সট নোড অনুবাদ হয়।

JSON লোকেল ফাইল অনুবাদ

একটি সাধারণ ব্যবহার হলো লোকেল ফাইল অনুবাদ করা। পুরো অবজেক্ট 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"
    );
}

একটি রিকোয়েস্ট তিনটি লোকেল হ্যান্ডেল করে। প্রতিটি আউটপুট ফাইলে কী অপরিবর্তিত থাকে।

ব্যাচ রিকোয়েস্ট

যখন আপনার একাধিক আলাদা কনটেন্ট আইটেম অনুবাদ করতে হয় তখন batch() ব্যবহার করুন। আপনি একক রিকোয়েস্টে সর্বোচ্চ ১০০ আইটেম পাঠাতে পারেন, প্রতিটির নিজস্ব 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,  // মোট অপেক্ষার সময়, ডিফল্ট ২০ মিনিট
    // '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() ব্যর্থ জবের আইডি দেয় যাতে আপনি লগ করতে বা ব্যবহারকারীর সামনে দেখাতে পারেন।

দ্রুত রেফারেন্স

মেথডএন্ডপয়েন্টপ্রমাণীকরণ প্রয়োজন
$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 + পোলিংহ্যাঁ

শুরু করুন

SDK Packagist-এ আছে usepolylingo/polylingo। পূর্ণ API ডকুমেন্টেশন আছে usepolylingo.com/docs।

ফ্রি টিয়ার প্রতি মাসে ৫০,০০০ টোকেন অন্তর্ভুক্ত করে। কোনো ক্রেডিট কার্ডের প্রয়োজন নেই।

composer require usepolylingo/polylingo

আপনার API কী পান