← ब्लॉग पर वापस जाएं
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 (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 के लिए, टैग और गुण संरक्षित रहते हैं और केवल टेक्स्ट नोड्स का अनुवाद किया जाता है।

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() का उपयोग करें। आप एकल अनुरोध में 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 संरक्षित रखती है, ताकि आप परिणामों को अपने मूल डेटा से बिना क्रम पर निर्भर हुए मैप कर सकें।

असिंक्रोनस जॉब्स

लंबे चलने वाले अनुवादों (बड़े दस्तावेज़, कई लक्ष्य, या दोनों) के लिए jobs 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 + पोलिंगहाँ

शुरू करें

SDK Packagist पर usepolylingo/polylingo पर है। पूर्ण API दस्तावेज़ usepolylingo.com/docs पर है।

मुफ्त स्तर में प्रति माह 50,000 टोकन शामिल हैं। किसी क्रेडिट कार्ड की आवश्यकता नहीं।

composer require usepolylingo/polylingo

अपनी API कुंजी प्राप्त करें