Node.js SDK (polylingo)

Klien resmi berbasis TypeScript untuk PolyLingo REST API. Menggunakan runtime fetch (Node.js 18+), dikirim sebagai ESM dan CJS, dan tidak memiliki dependensi runtime selain Node.

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

Untuk detail HTTP mentah, lihat API reference.

Instalasi

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', // opsional; ini default
  timeout: 120_000, // opsional; batas waktu permintaan dalam milidetik (default 120_000)
})

Metode

client.health()

GET /health — tidak perlu autentikasi di server; klien tetap mengirim header Authorization jika dikonfigurasi.

Mengembalikan { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — daftar bahasa yang didukung.

const { languages } = await client.languages()

client.translate(params)

POST /translate

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

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

client.usage()

GET /usage — penggunaan paket untuk kunci yang terautentikasi.

const u = await client.usage()

Pekerjaan — client.jobs

client.jobs.create(params)

POST /jobs — mengantri pekerjaan asinkron. Menyelesaikan dengan body 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 — polling status. Saat status === 'completed', API mengembalikan translations dan usage di tingkat atas objek JSON (tidak di bawah result).

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

client.jobs.translate(params) — kemudahan

Mengirimkan pekerjaan, lalu melakukan polling sampai completed atau failed, atau sampai anggaran polling habis.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms antara polling; default 5_000
  timeout: 600_000,     // anggaran total ms untuk polling; default 20 menit
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // opsional; dipanggil saat dalam antrean/proses
})

done.translations.de
done.usage.total_tokens

Siklus hidup pekerjaan di API menggunakan status pending, processing, completed, dan failed.

Penanganan kesalahan

Semua kegagalan dari SDK (kecuali bug) memperluas 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 valid */ }
  else if (e instanceof RateLimitError) { /* e.retryAfter */ }
  else if (e instanceof JobFailedError) { /* e.jobId */ }
  else if (e instanceof PolyLingoError) { /* e.status, e.error */ }
}

Pola pekerjaan asinkron (ringkasan)

1. Polling fire-and-forget: jobs.create → pekerja Anda memanggil jobs.get secara berkala sampai completed atau failed.
2. Polling bawaan: jobs.translate — semantik sama, dengan pollInterval, timeout, dan onProgress.

Payload besar dan terjemahan yang berjalan lama harus memilih jobs daripada translate sinkron untuk menghindari timeout HTTP.

TypeScript

Paket mengekspor tipe untuk opsi, hasil, dan kesalahan. Impor tipe bernama dari polylingo sesuai kebutuhan (lihat dist/index.d.ts yang dipublikasikan).

Changelog

0.1.0

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