متن کے ترجمے کی API

یہ API متن کا ترجمہ قطار میں موجود جابز کے طور پر کرتی ہے، ہر جاب میں ایک ہدف زبان کے لیے۔ متن بھیجیں، واپس ملنے والی جاب کی شناخت محفوظ رکھیں اور عمل مکمل ہونے تک جاب حاصل کرتے رہیں۔ ہر درخواست HTTPS پر اپنے اکاؤنٹ کی اسناد کے ساتھ بھیجیں، مثالوں میں دکھائی گئی HTTP Basic اسناد یا API ٹوکن استعمال کریں، جیسا کہ اس حصے میں بیان کیا گیا ہے: توثیق۔ اسناد اپنے سرور پر رکھیں۔

اینڈ پوائنٹس

دو API میزبان، https://api.multi.tel اور مطابقت کے میزبان https://api.multitel.net، اکاؤنٹ تک محدود ایک ہی جابز، آئڈیم پوٹنسی کیز، حدود اور بلنگ استعمال کرتے ہیں۔ جواب کے بیرونی ڈھانچے میں فرق ہے، اس لیے مسلسل ایک ہی میزبان اور اس کے مطابق پارسر استعمال کریں۔

میزبان api.multi.tel پر، ہر پاتھ سابقے /v1/translate کے ساتھ بھی دستیاب ہے، جو /v3/translate کی جگہ آتا ہے۔ میزبان api.multitel.net پر، /v3/translate والے پاتھ استعمال کریں۔

سروس کی معلومات کا جواب یہ فیلڈز بتاتا ہے: enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000)، cpuLanguages اور ratesNanosPerCharacter. cpuLanguages معیاری ترجمے کے لیے قبول شدہ بنیادی زبانوں کے کوڈز کی فہرست دیتا ہے۔ ratesNanosPerCharacter ہر انجن کے لیے ماخذ کے ہر کوڈ پوائنٹ کی مقررہ قیمت بتاتا ہے، امریکی ڈالر کے اربویں حصوں میں: 5000 کی قدر کا مطلب ہر دس لاکھ کوڈ پوائنٹس کے لیے $5 ہے۔ جواب یہ نہیں بتاتا کہ بہتر ترجمہ اس وقت دستیاب ہے یا نہیں؛ دستیاب نہ ہونے پر بہتر ترجمے کا تخمینہ 503 لوٹاتا ہے۔ معلومات پڑھنا مفت ہے۔

متن کا ترجمہ کریں

JSON کو Content-Type: application/json کے ساتھ اس پتے پر بھیجیں: POST https://api.multi.tel/v3/translate۔ ہر جاب کی ایک ہدف زبان ہے، اس لیے ہر ہدف کے لیے الگ جاب بھیجیں۔

لوکیل کوڈز BCP 47 ٹیگز ہیں جن میں 2 سے 63 حروف، ہندسے اور ہائفن ہوتے ہیں۔ انہیں معیاری صورت میں بدلا جاتا ہے، اس لیے en-us کو en-US کے طور پر محفوظ کیا جاتا ہے۔ غلط ٹیگز، اور und, mul یا zxx، 400 invalid_translation_language لوٹاتے ہیں۔ معیاری ترجمے کی دستیابی بنیادی زبان سے جانچی جاتی ہے، اور nb اور nn کو no سمجھا جاتا ہے۔ علاقائی ہدف جیسے fr-CA کو قبول کر کے محفوظ کیا جاتا ہے، مگر معیاری نتیجہ بنیادی زبان کی پیروی کرتا ہے اور اس کے علاقے کی عکاسی کی ضمانت نہیں۔

اس میزبان پر درخواست کی باڈی 128 KiB کے اندر رکھیں۔ ہر غیر ASCII حرف کو \u سلسلے میں بدلنے کے بجائے متن UTF-8 میں بھیجیں، ورنہ 20,000 حروف کی درخواست حد سے بڑھ سکتی ہے۔

باڈی صرف ان چار فیلڈز کو قبول کرتی ہے۔ کوئی بھی دوسری پراپرٹی 400 invalid_translation_request کے ساتھ مسترد ہوتی ہے، بشمول idempotency_key، مالک کی شناختیں، مفت پراسیسنگ کے فلیگز اور حصوں کی صفیں۔

آئڈیم پوٹنسی اور دوبارہ استعمال

ہر ارسال کے لیے Idempotency-Key ہیڈر درکار ہے جس کی لمبائی 1 سے 190 حروف ہو۔ ASCII حروف، ہندسے، -, _, . اور : استعمال کریں، شروع یا آخر میں خالی جگہیں نہ ہوں؛ غائب کی یا 191 یا زیادہ حروف کی کی 400 کے ساتھ مسترد ہوتی ہے۔ کیز آپ کے اکاؤنٹ اور ترجمے کی سروس تک محدود ہیں، دونوں میزبانوں اور اکاؤنٹ کی تمام اسناد پر۔

• اسی کی کے ساتھ وہی متن، معیاری صورت والی وہی زبانیں اور وہی انجن موجودہ جاب کو HTTP 200 اور duplicate: true کے ساتھ لوٹاتے ہیں، بغیر اضافی معاوضے کے۔
• اسی کی کے ساتھ مختلف متن، زبانیں یا انجن 409 idempotency_conflict لوٹاتے ہیں۔ اگر جاب بننے کے بعد پراسیسنگ کا ورژن بدل چکا ہو تو بھی وہی کی 409 لوٹاتی ہے۔ اس صورت میں دوبارہ بھیجنے کے بجائے اصل جاب اس کی شناخت سے پڑھیں۔
• نئی کی کے ساتھ وہی متن، معیاری صورت والی وہی زبانیں اور وہی انجن موجودہ جاب کو HTTP 200 اور duplicate: true کے ساتھ لوٹاتے ہیں، بغیر نئے پراسیسنگ معاوضے کے، اگر اس مواد اور موجودہ پراسیسنگ ورژن کی جاب قطار میں ہو، چل رہی ہو، مکمل ہو یا ادائیگی کی منتظر ہو۔ دوبارہ استعمال شدہ جاب ادائیگی کی منتظر ہو تو ادائیگی اب بھی مکمل کرنا ضروری ہے۔ ناکام جابز دوبارہ استعمال نہیں ہوتیں: نئی جاب بنتی ہے اور مکمل ہونے پر معاوضہ لیا جاتا ہے۔

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

نئی جاب HTTP 202 لوٹاتی ہے۔ مثال کے متن میں 57 کوڈ پوائنٹس ہیں، اس لیے ہر دس لاکھ کوڈ پوائنٹس کے لیے $5 کی شرح پر اس کی لاگت $0.000285 ہے۔ مختصر جواب (شناخت ایک مثال ہے):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

ارسال پر 402 insufficient_balance بھی مل سکتا ہے جب پیشگی ادا شدہ بیلنس اس جاب اور آپ کی دیگر نامکمل جابز کی مجموعی لاگت کے لیے کافی نہ ہو، اور 429 translation_queue_full جب آپ کے اکاؤنٹ یا سروس میں بہت زیادہ نامکمل جابز ہوں۔ درج ذیل صورتوں میں 503 ملتا ہے:

• paid_translation_not_enabled جب بامعاوضہ ترجمہ بند ہو۔
• translation_unavailable بہتر ترجمے کی درخواست پر جب بہتر ترجمہ دستیاب نہ ہو۔
• translation_pricing_unavailable جب منتخب انجن کی کوئی شرح مقرر نہ ہو۔

429 اور 503 کے جوابات پر بعد میں اسی کی کے ساتھ دوبارہ کوشش کریں۔

معیار منتخب کریں

لمبا متن چھوٹے ٹکڑوں میں پراسیس ہو کر دوبارہ جوڑا جاتا ہے۔ نئی سطریں اور فاصلہ بدل سکتے ہیں، اور پراسیسنگ کے ٹکڑوں کی سرحد پر جملہ سیاق کھو سکتا ہے۔ اصل متن محفوظ رکھیں اور جڑا ہوا نتیجہ جانچیں۔ معیاری ترجمہ علاقائی ٹیگ کی بنیادی زبان استعمال کرتا ہے؛ ٹیگ قبول اور محفوظ ہونے سے علاقائی الفاظ کی ضمانت نہیں ملتی۔

معیاری ترجمہ CPU ورکرز پر چلتا ہے۔ بہتر ترجمہ متن کو مقررہ بیرونی AI سروس کو بھیجتا ہے۔ اس کا نتیجہ بھی جانچنا ضروری ہے؛ سروس یہ ضمانت نہیں دیتی کہ ایک انجن ہر زبانوں کے جوڑے یا قسم کے متن کے لیے زیادہ درست ہوگا۔

معیاری ترجمہ ایک مسودہ ہے جس کا معیار اور پراسیسنگ کا وقت زبانوں کے جوڑے کے لحاظ سے بدلتا ہے۔ بہتر ترجمہ ایسے متن کے لیے ہے جس میں سیاق اہم ہو، مگر اس میں بھی اہم ناموں، نمبروں، نفی اور وعدوں کی جانچ ضروری ہے۔ کوئی بھی طریقہ اصل آڈیو متن میں پہلے سے موجود غلطیاں درست نہیں کرتا، اس لیے موازنے کے لیے اصل محفوظ رکھیں۔

اسی API میزبان پر GET /v3/translate استعمال کر کے موجودہ دستیابی، معیاری ترجمے کی معاون زبانیں اور مقررہ شرحیں دیکھیں۔ معیاری درخواست میں ماخذ یا ہدف کی بنیادی زبان cpuLanguages میں نہ ہو تو 422 translation_language_pair_unavailable ملتا ہے۔ جب source_language دیا گیا ہو اور اس کی بنیادی زبان ہدف جیسی ہو تو درخواست جاب بنانے کے بجائے 409 translation_same_language لوٹاتی ہے۔ بہتر ترجمہ الگ سے فعال ہوتا ہے: دستیاب نہ ہونے پر اس کی درخواستیں اور تخمینے 503 لوٹاتے ہیں۔

پہلے تخمینہ لیں

میزبان api.multi.tel پر وہی JSON باڈی اس پتے پر بھیجیں: POST /v3/translate/estimate۔ آئڈیم پوٹنسی کی درکار نہیں۔ تخمینہ وہی توثیق لاگو کرتا ہے، بشمول 422 اور 409 کی جانچیں، مگر جاب نہیں بناتا، متن کا ترجمہ نہیں کرتا، رقم محفوظ نہیں کرتا، آپ کا بیلنس نہیں دیکھتا اور اکاؤنٹ سے معاوضہ نہیں لیتا۔ یہ HTTP 200 لوٹاتا ہے، جس میں estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd اور costUsd، data کے تحت ہوتے ہیں۔ اوپر کی مثال میں، costUsd کی قدر 0.000285000 ہے معیاری شرح پر۔ بہتر ترجمہ دستیاب نہ ہو تو بہتر ترجمے کا تخمینہ 503 service_unavailable لوٹاتا ہے۔ تخمینے موجودہ مقررہ شرح استعمال کرتے ہیں۔ جاب کی شرح اسے بناتے وقت مقرر ہوتی ہے، اور اسی شرح پر اس کا معاوضہ لیا جاتا ہے۔

ترجمہ حاصل کریں

نیا ارسال HTTP 202 لوٹاتا ہے، جبکہ موجودہ یا دوبارہ استعمال شدہ جاب HTTP 200 لوٹاتی ہے۔ data.id محفوظ رکھیں اور مشترکہ جاب کا طریقۂ کار استعمال کریں۔ جاب کے آبجیکٹ میں یہ فیلڈز شامل ہیں:

• id, status, engine, sourceLocale اور targetLocale۔
• sourceCharacters, costUsd, costIsEstimate اور pricePerMillionCharactersUsd۔
• progress اور createdAt۔
• modelVersion، پراسیسنگ کے ورژن کی ایسی اسٹرنگ جس کی اندرونی ساخت پر انحصار نہیں کرنا چاہیے۔
• duplicate دوبارہ استعمال والے جوابات میں۔
• failureCode ناکام جابز کے لیے: translation_failed, translation_timeout, input_failed یا worker_lease_lost۔

ناکام جاب میں costUsd کی قدر صفر ہوتی ہے۔

مکمل جاب میں data.result ہوتا ہے، جس میں sourceLocale (خالی اگر ماخذ زبان نہ دی گئی ہو)، targetLocale، ترجمہ شدہ text (حصوں کے متن نئی سطروں سے جڑے ہوئے)، اور segments شامل ہوتے ہیں۔ اس API سے بھیجے گئے متن کے لیے، segments میں ایک اندراج ہوتا ہے جس میں ترجمہ شدہ text اور ہدف زبان کا language ہوتا ہے۔ ادائیگی کی منتظر جابز کے نتائج ادائیگی مکمل ہونے تک روکے جاتے ہیں۔

api.multitel.net کا استعمال

مطابقت کا اینڈ پوائنٹ POST https://api.multitel.net/v3/translate وہی JSON فیلڈز اور وہی Idempotency-Key ہیڈر قبول کرتا ہے۔ ہیڈر غائب ہو تو یہ JSON باڈی میں idempotency_key اسٹرنگ بھی قبول کرتا ہے۔ کوئی بھی دوسری اضافی فیلڈ 400 unsupported_translation_option کے ساتھ مسترد ہوتی ہے۔ اس میزبان پر خام باڈی زیادہ سے زیادہ 256,000 بائٹس ہو سکتی ہے، اور 20,000 کوڈ پوائنٹس سے زیادہ متن 413 translation_too_large لوٹاتا ہے، 400 کے بجائے۔ خالی source_language کو غیر موجود سمجھا جاتا ہے۔ 429 کے جواب میں Retry-After: 15 شامل ہوتا ہے۔ یہ میزبان یہ خرابیاں بھی لوٹاتا ہے:

• 400 json_body_required جب باڈی غائب ہو، غلط JSON ہو یا JSON کی اسکیلر قدر ہو۔ JSON آبجیکٹ بھیجیں۔
• 400 invalid_translation_options جب text, target_language یا engine غائب، خالی یا اسٹرنگ نہ ہو، یا source_language اسٹرنگ نہ ہو۔
• 400 invalid_translation_text صرف خالی جگہوں والے متن کے لیے۔
• 400 invalid_translation_engine نامعلوم انجن کے لیے۔
• 400 idempotency_key_required غائب، خالی یا حد سے لمبی کی، یا غیر اسٹرنگ idempotency_key کے لیے۔
• 400 invalid_job غلط ساخت کی جاب شناخت کے لیے۔

اس میزبان کی ترجمے کی سروس کے جوابات یہ بیرونی ڈھانچہ استعمال کرتے ہیں: {"status":{"code":HTTP_STATUS},"response":{...}}، جس میں status آبجیکٹ ہے۔ جاب کی شناخت response.id سے اور مکمل نتیجہ response.result سے پڑھیں۔ خرابیوں میں کوڈ response.code میں ہوتا ہے، پیغام یا درخواست کی شناخت کے بغیر۔ توثیق کی ناکامیاں (401) میزبان کی عمومی سائن اِن جانچ سے لوٹتی ہیں اور ان کی باڈی مختلف ہو سکتی ہے، اس لیے پارس کرنے سے پہلے HTTP اسٹیٹس دیکھیں۔ جابز بنیادی میزبان کے ساتھ مشترک ہیں، مگر وقفے وقفے سے جاب حاصل کرنے، ادائیگی مکمل کرنے اور استعمال کے لیے ایک ہی میزبان رکھیں تاکہ آپ کا پارسر جواب کے بیرونی ڈھانچے کے مطابق ہو۔ یہ میزبان وہی JSON فیلڈز اس پتے پر بھی قبول کرتا ہے: /v3/translate/estimate، آئڈیم پوٹنسی کی کے بغیر، اور اس کا تخمینہ response کے تحت ہوتا ہے۔