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 // string
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, // पोल के बीच ms; डिफ़ॉल्ट 5_000
  timeout: 600_000,     // पोलिंग के लिए **कुल** ms बजट; डिफ़ॉल्ट 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.2

• रखरखाव: डिफ़ॉल्ट API बेस URL https://api.usepolylingo.com/v1 है।

0.1.0

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