Node.js SDK (polylingo)

לקוח רשמי מבוסס TypeScript ל-PolyLingo REST API. משתמש בריצה 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,     // תקציב כולל במילישניות לפולינג; ברירת מחדל 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.

Payloads גדולים ותרגומים ארוכי טווח צריכים להעדיף jobs על פני translate סינכרוני כדי למנוע תקלות HTTP.

TypeScript

החבילה מייצאת טיפוסים לאפשרויות, תוצאות, ושגיאות. ייבא טיפוסים בשם מ-polylingo לפי הצורך (ראה dist/index.d.ts שפורסם).

יומן שינויים

0.1.0

• גרסה ראשונית: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.