Node.js SDK (polylingo)

PolyLingo REST API-এর জন্য অফিসিয়াল TypeScript ক্লায়েন্ট। এটি রানটাইম fetch (Node.js 18+) ব্যবহার করে, ESM এবং CJS হিসেবে সরবরাহ করা হয়, এবং Node ছাড়া কোন রানটাইম নির্ভরতা নেই।

• npm: polylingo
• সোর্স: UsePolyLingo/polylingo-node

কাঁচা HTTP বিবরণের জন্য দেখুন API reference।

ইনস্টলেশন

npm install polylingo

Node.js: >= 18

কনস্ট্রাক্টর

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // প্রয়োজনীয়
  baseURL: 'https://api.usepolylingo.com/v1', // ঐচ্ছিক; এটি ডিফল্ট
  timeout: 120_000, // ঐচ্ছিক; অনুরোধ টাইমআউট মিলিসেকেন্ডে (ডিফল্ট 120_000)
})

মেথডসমূহ

client.health()

GET /health। সার্ভারে কোন অথেন্টিকেশন প্রয়োজন নেই; ক্লায়েন্ট কনফিগার করা থাকলে Authorization হেডার পাঠায়।

ফিরে দেয় { status, timestamp }।

const h = await client.health()

client.languages()

GET /languages। সমর্থিত ভাষার তালিকা ফেরত দেয়।

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // ঐচ্ছিক; API স্বয়ংক্রিয় সনাক্তকরণের জন্য বাদ দিন
  source: 'en',       // ঐচ্ছিক ইঙ্গিত
  model: 'standard',  // ঐচ্ছিক: 'standard' | 'advanced'
})

r.translations.es // স্ট্রিং
r.usage.total_tokens
r.usage.input_tokens
r.usage.output_tokens

client.batch(params)

POST /translate/batch

const b = await client.batch({
  items: [
    { id: 'a', content: 'Hello' },
    { id: 'b', content: '## Title', format: 'markdown' },
  ],
  targets: ['de'],
  source: 'en',    // ঐচ্ছিক
  model: 'standard', // ঐচ্ছিক
})

b.results[0].translations.de
b.usage.total_tokens

client.usage()

GET /usage। প্রমাণীকৃত কী-এর জন্য প্ল্যান ব্যবহারের তথ্য ফেরত দেয়।

const u = await client.usage()

কাজসমূহ (client.jobs)

client.jobs.create(params)

POST /jobs। অ্যাসিঙ্ক্রোনাস কাজ কিউ করে এবং 202 JSON বডি (job_id, status, created_at, …) রেজল্ভ করে।

const job = await client.jobs.create({
  content: longMarkdown,
  targets: ['de', 'fr'],
  format: 'markdown',
})
console.log(job.job_id)

client.jobs.get(jobId)

GET /jobs/:id। স্ট্যাটাস পোল করে। যখন status === 'completed', API JSON অবজেক্টের শীর্ষ স্তরে translations এবং usage ফেরত দেয় (যা result এর অধীনে নয়)।

const status = await client.jobs.get(job.job_id)

client.jobs.translate(params) (সহজীকরণ)

একটি কাজ সাবমিট করে, তারপর পোল করে যতক্ষণ না completed বা failed হয়, অথবা টাইমআউট হয়।

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // পোলের মধ্যে মিলিসেকেন্ড; ডিফল্ট 5_000
  timeout: 600_000,     // পোলিংয়ের জন্য **মোট** মিলিসেকেন্ড বাজেট; ডিফল্ট ২০ মিনিট
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // ঐচ্ছিক; কিউ/প্রসেসিং চলাকালীন কল করা হয়
})

done.translations.de
done.usage.total_tokens

API-তে কাজের জীবনচক্রে pending, processing, completed, এবং failed স্ট্যাটাস ব্যবহার হয়।

ত্রুটি পরিচালনা

SDK থেকে সব ব্যর্থতা (বাগ বাদে) PolyLingoError থেকে উত্তরাধিকার সূত্রে প্রাপ্ত:

import PolyLingo, {
  PolyLingoError,
  AuthError,
  RateLimitError,
  JobFailedError,
} from 'polylingo'

try {
  await client.translate({ content: 'Hi', targets: ['es'] })
} catch (e) {
  if (e instanceof AuthError) { /* অবৈধ কী */ }
  else if (e instanceof RateLimitError) { /* e.retryAfter */ }
  else if (e instanceof JobFailedError) { /* e.jobId */ }
  else if (e instanceof PolyLingoError) { /* e.status, e.error */ }
}

অ্যাসিঙ্ক্রোনাস কাজের প্যাটার্ন (সারাংশ)

1. ফায়ার-অ্যান্ড-ফরগেট পোলিং: jobs.create → আপনার ওয়ার্কার নির্দিষ্ট সময় অন্তর jobs.get কল করে যতক্ষণ না completed বা failed হয়।
2. বিল্ট-ইন পোলিং: jobs.translate। একই সেমান্টিক্স, pollInterval, timeout, এবং onProgress সহ।

বড় পে-লোড এবং দীর্ঘমেয়াদী অনুবাদের জন্য HTTP টাইমআউট এড়াতে jobs ব্যবহার করা উচিত translate এর পরিবর্তে।

TypeScript

প্যাকেজটি অপশন, ফলাফল, এবং ত্রুটির জন্য টাইপ রপ্তানি করে। প্রয়োজন অনুযায়ী polylingo থেকে নামকৃত টাইপগুলি ইমপোর্ট করুন (প্রকাশিত dist/index.d.ts দেখুন)।

পরিবর্তন লগ

0.1.2

• রক্ষণাবেক্ষণ: ডিফল্ট API বেস URL হল https://api.usepolylingo.com/v1।

0.1.0

• প্রাথমিক রিলিজ: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate।