Node.js SDK (polylingo)

PolyLingo REST API 的官方 TypeScript 优先客户端。它使用运行时 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 — 将异步工作入队。返回 202 JSON 主体（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 在 JSON 对象的顶层返回 translations 和 usage（不嵌套在 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. 发起即忘轮询： jobs.create → 你的工作者定期调用 jobs.get，直到 completed 或 failed。
2. 内置轮询： jobs.translate — 相同语义，带有 pollInterval、timeout 和 onProgress。

大型负载和长时间运行的翻译应优先使用 jobs，避免同步 translate 导致 HTTP 超时。

TypeScript

该包导出选项、结果和错误的类型。根据需要从 polylingo 导入命名类型（参见发布的 dist/index.d.ts）。

更新日志

0.1.0

• 初始发布：health、languages、translate、batch、usage、jobs.create、jobs.get、jobs.translate。