Node.js SDK (polylingo)

کلاینت رسمی TypeScript برای PolyLingo REST API. از runtime 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. کار ناهمزمان را در صف قرار می‌دهد و با بدنه JSON 202 (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 translations و usage را در سطح بالا شی JSON برمی‌گرداند (نه در زیر 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,     // بودجه **کل** میلی‌ثانیه برای polling؛ پیش‌فرض ۲۰ دقیقه
  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. Polling بدون انتظار: jobs.create → کارگر شما به صورت دوره‌ای jobs.get را تا completed یا failed فراخوانی می‌کند.
2. Polling داخلی: jobs.translate. همان معنا، با pollInterval، timeout و onProgress.

بارهای بزرگ و ترجمه‌های طولانی باید کارها را به جای translate همزمان ترجیح دهند تا از تایم‌اوت HTTP جلوگیری کنند.

TypeScript

بسته انواعی برای گزینه‌ها، نتایج و خطاها صادر می‌کند. انواع نام‌دار را از polylingo به دلخواه وارد کنید (به dist/index.d.ts منتشر شده مراجعه کنید).

تغییرات

0.1.2

• نگهداری: URL پایه API پیش‌فرض https://api.usepolylingo.com/v1 است.

0.1.0

• انتشار اولیه: health، languages، translate، batch، usage، jobs.create، jobs.get، jobs.translate.