Node.js SDK (polylingo)

Khách hàng TypeScript chính thức cho PolyLingo REST API. Nó 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 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 yêu cầu 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. Trả về 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 để API tự động phát hiện
  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. Trả về việc sử dụng gói 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 và trả về JSON body 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 cao nhất của đối tượng JSON (không nằm dưới 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 liên tục cho đến khi completed hoặc failed, hoặc hết thời gian chờ.

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,     // tổng thời gian 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 xếp hàng/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 từ 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. Gửi và quên kiểm tra: 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à bản dịch lâu nên ưu tiên công việc thay vì translate đồng bộ để tránh timeout 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ên từ polylingo khi cần (xem dist/index.d.ts đã xuất bản).

Nhật ký thay đổi

0.1.2

• Bảo trì: URL cơ sở API mặc định là https://api.usepolylingo.com/v1.

0.1.0

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