Node.js SDK (polylingo)

Khách hàng chính thức ưu tiên TypeScript cho PolyLingo REST API. Sử dụng runtime fetch (Node.js 18+), đóng gói dưới dạng ESM và CJS, và không có phụ thuộc runtime ngoài Node.

• npm: polylingo
• Nguồn: UsePolyLingo/polylingo-node

Để biết chi tiết HTTP thô, xem API reference.

Cài đặt

npm install polylingo

Node.js: >= 18

Hàm khởi tạo

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // bắt buộc
  baseURL: 'https://api.usepolylingo.com/v1', // tùy chọn; đây là mặc định
  timeout: 120_000, // tùy chọn; thời gian chờ yêu cầu tính bằng mili giây (mặc định 120_000)
})

Các phương thức

client.health()

GET /health — không cần xác thực trên máy chủ; khách hàng vẫn gửi header Authorization nếu được cấu hình.

Trả về { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — danh sách ngôn ngữ được hỗ trợ.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // tùy chọn — bỏ qua = tự động phát hiện trên API
  source: 'en',       // gợi ý tùy chọn
  model: 'standard',  // tùy chọn: 'standard' | 'advanced'
})

r.translations.es // chuỗi
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',    // tùy chọn
  model: 'standard', // tùy chọn
})

b.results[0].translations.de
b.usage.total_tokens

client.usage()

GET /usage — sử dụng kế hoạch cho khóa đã xác thực.

const u = await client.usage()

Công việc — client.jobs

client.jobs.create(params)

POST /jobs — đưa công việc bất đồng bộ vào hàng đợi. Trả về 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 — kiểm tra trạng thái. Khi status === 'completed', API trả về translations và usage ở cấp độ trên cùng của đối tượng JSON (không nằm trong result).

const status = await client.jobs.get(job.job_id)

client.jobs.translate(params) — tiện lợi

Gửi một công việc, sau đó kiểm tra cho đến khi completed hoặc failed, hoặc cho đến khi hết ngân sách kiểm tra.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms giữa các lần kiểm tra; mặc định 5_000
  timeout: 600_000,     // ngân sách **tổng cộng** ms cho việc kiểm tra; mặc định 20 phút
  onProgress: (pos) => console.log(`Vị trí trong hàng đợi: ${pos}`), // tùy chọn; gọi khi đang trong hàng đợi/xử lý
})

done.translations.de
done.usage.total_tokens

Vòng đời công việc trên API sử dụng các trạng thái pending, processing, completed và failed.

Xử lý lỗi

Tất cả lỗi từ SDK (ngoại trừ lỗi lập trình) mở rộng PolyLingoError:

import PolyLingo, {
  PolyLingoError,
  AuthError,
  RateLimitError,
  JobFailedError,
} from 'polylingo'

try {
  await client.translate({ content: 'Hi', targets: ['es'] })
} catch (e) {
  if (e instanceof AuthError) { /* khóa không hợp lệ */ }
  else if (e instanceof RateLimitError) { /* e.retryAfter */ }
  else if (e instanceof JobFailedError) { /* e.jobId */ }
  else if (e instanceof PolyLingoError) { /* e.status, e.error */ }
}

Mẫu công việc bất đồng bộ (tóm tắt)

1. Kiểm tra "bắn và quên": jobs.create → worker của bạn gọi jobs.get theo khoảng thời gian cho đến khi completed hoặc failed.
2. Kiểm tra tích hợp: jobs.translate — cùng ý nghĩa, với pollInterval, timeout, và onProgress.

Payload lớn và dịch dài nên ưu tiên công việc thay vì translate đồng bộ để tránh hết thời gian HTTP.

TypeScript

Gói xuất các kiểu cho tùy chọn, kết quả và lỗi. Nhập các kiểu được đặt tên từ polylingo khi cần (xem dist/index.d.ts đã phát hành).

Nhật ký thay đổi

0.1.0

• Phát hành ban đầu: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.