Node.js SDK (polylingo)

Klien rasmi TypeScript-pertama untuk PolyLingo REST API. Ia menggunakan runtime fetch (Node.js 18+), dihantar sebagai ESM dan CJS, dan tiada kebergantungan runtime selain Node.

• npm: polylingo
• Sumber: UsePolyLingo/polylingo-node

Untuk butiran HTTP mentah, lihat rujukan API.

Pemasangan

npm install polylingo

Node.js: >= 18

Konstruktor

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // wajib
  baseURL: 'https://api.usepolylingo.com/v1', // pilihan; ini lalai
  timeout: 120_000, // pilihan; masa tamat permintaan dalam milisaat (lalai 120_000)
})

Kaedah

client.health()

GET /health — tiada pengesahan diperlukan pada pelayan; klien masih menghantar header Authorization jika dikonfigurasikan.

Mengembalikan { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — senarai bahasa yang disokong.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // pilihan — diabaikan = pengesanan automatik pada API
  source: 'en',       // petunjuk pilihan
  model: 'standard',  // pilihan: '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',    // pilihan
  model: 'standard', // pilihan
})

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

client.usage()

GET /usage — penggunaan pelan untuk kunci yang disahkan.

const u = await client.usage()

Tugasan — client.jobs

client.jobs.create(params)

POST /jobs — masukkan kerja asinkron. Menyelesaikan dengan badan 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 — semak status. Apabila status === 'completed', API mengembalikan translations dan usage pada peringkat atas objek JSON (bukan di bawah result).

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

client.jobs.translate(params) — kemudahan

Menghantar tugasan, kemudian semak sehingga completed atau failed, atau sehingga bajet semakan habis.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms antara semakan; lalai 5_000
  timeout: 600_000,     // bajet ms **jumlah** untuk semakan; lalai 20 minit
  onProgress: (pos) => console.log(`Kedudukan barisan: ${pos}`), // pilihan; dipanggil semasa beratur/memproses
})

done.translations.de
done.usage.total_tokens

Kitar hayat tugasan pada API menggunakan status pending, processing, completed, dan failed.

Pengendalian ralat

Semua kegagalan dari SDK (kecuali pepijat) mewarisi PolyLingoError:

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

try {
  await client.translate({ content: 'Hi', targets: ['es'] })
} catch (e) {
  if (e instanceof AuthError) { /* kunci tidak sah */ }
  else if (e instanceof RateLimitError) { /* e.retryAfter */ }
  else if (e instanceof JobFailedError) { /* e.jobId */ }
  else if (e instanceof PolyLingoError) { /* e.status, e.error */ }
}

Corak tugasan asinkron (ringkasan)

1. Semakan tanpa tunggu: jobs.create → pekerja anda panggil jobs.get secara berkala sehingga completed atau failed.
2. Semakan terbina dalam: jobs.translate — semantik sama, dengan pollInterval, timeout, dan onProgress.

Payload besar dan terjemahan lama harus menggunakan jobs berbanding translate segerak untuk mengelakkan tamat masa HTTP.

TypeScript

Pakej mengeksport jenis untuk pilihan, hasil, dan ralat. Import jenis bernama dari polylingo mengikut keperluan (lihat dist/index.d.ts yang diterbitkan).

Log perubahan

0.1.0

• Pelepasan awal: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.