Node.js SDK (polylingo)

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

Metode

client.health()

GET /health. Tidak perlu otentikasi di server; klien tetap mengirim header Authorization jika dikonfigurasi.

Mengembalikan { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages. Mengembalikan 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; hilangkan agar API mendeteksi otomatis
  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. Mengembalikan penggunaan paket untuk kunci yang terautentikasi.

const u = await client.usage()

Jobs (client.jobs)

client.jobs.create(params)

POST /jobs. Mengantri pekerjaan asinkron dan 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. Melakukan polling status. Ketika status === 'completed', API mengembalikan translations dan usage pada tingkat atas objek JSON (tidak bersarang di bawah result).

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

client.jobs.translate(params) (kenyamanan)

Mengirimkan pekerjaan, lalu melakukan polling sampai completed atau failed, atau sampai batas waktu tercapai.

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 waktu **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 error

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 sebaiknya menggunakan jobs daripada translate sinkron untuk menghindari timeout HTTP.

TypeScript

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

Changelog

0.1.2

• Pemeliharaan: URL dasar API default adalah https://api.usepolylingo.com/v1.

0.1.0

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