Node.js SDK (polylingo)

العميل الرسمي القائم على TypeScript أولاً لواجهة برمجة تطبيقات PolyLingo REST. يستخدم وقت التشغيل fetch (Node.js 18+)، يُشحن كـ ESM و CJS، ولا يحتوي على اعتمادات وقت تشغيل بخلاف Node.

• npm: polylingo
• المصدر: UsePolyLingo/polylingo-node

للحصول على تفاصيل HTTP الخام، راجع مرجع API.

التثبيت

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,     // ميزانية **إجمالية** بالميلي ثانية للاستعلام؛ الافتراضي 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.

يجب تفضيل الوظائف على translate المتزامن للحمولات الكبيرة والترجمات طويلة الأمد لتجنب انتهاء مهلة HTTP.

TypeScript

تصدّر الحزمة أنواعًا للخيارات، النتائج، والأخطاء. استورد الأنواع المسماة من polylingo حسب الحاجة (انظر dist/index.d.ts المنشور).

سجل التغييرات

0.1.0

• الإصدار الأول: health، languages، translate، batch، usage، jobs.create، jobs.get، jobs.translate.