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,     // पोलिंग के लिए **कुल** मिलीसेकंड बजट; डिफ़ॉल्ट 20 मिनट
  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 टाइमआउट से बचने के लिए सिंक्रोनस translate के बजाय jobs पसंद करना चाहिए।

TypeScript

पैकेज विकल्पों, परिणामों, और त्रुटियों के लिए प्रकार निर्यात करता है। आवश्यकतानुसार polylingo से नामित प्रकार आयात करें (प्रकाशित dist/index.d.ts देखें)।

चेंजलॉग

0.1.0

• प्रारंभिक रिलीज़: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate।