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.2

• صيانة: عنوان API الأساسي الافتراضي هو https://api.usepolylingo.com/v1.

0.1.0

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