Node.js SDK (polylingo)

ไคลเอนต์ TypeScript อย่างเป็นทางการสำหรับ PolyLingo REST API ใช้ runtime fetch (Node.js 18+), จัดส่งเป็น ESM และ CJS และไม่มี การพึ่งพาใน runtime นอกเหนือจาก 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 เข้าคิวงานแบบอะซิงโครนัสและส่งคืนร่าง 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(`ตำแหน่งคิว: ${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 แบบ fire-and-forget: jobs.create → worker ของคุณเรียก jobs.get เป็นช่วง ๆ จนกว่าจะ completed หรือ failed
2. Polling ในตัว: jobs.translate ความหมายเหมือนกัน พร้อม pollInterval, timeout และ onProgress

ข้อมูลขนาดใหญ่และการแปลที่ใช้เวลานานควรใช้ jobs แทน 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