Node.js SDK (polylingo)

Klien TypeScript rasmi 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!, // diperlukan
  baseURL: 'https://api.usepolylingo.com/v1', // pilihan; ini adalah lalai
  timeout: 120_000, // pilihan; had masa 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. Mengembalikan 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; boleh diabaikan untuk membiarkan API mengesan secara automatik
  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. Mengembalikan penggunaan pelan untuk kunci yang disahkan.

const u = await client.usage()

Pekerjaan (client.jobs)

client.jobs.create(params)

POST /jobs. Menyusun kerja async dan 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. Memeriksa status secara berkala. Apabila status === 'completed', API mengembalikan translations dan usage di peringkat atas objek JSON (bukan di bawah result).

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

client.jobs.translate(params) (kemudahan)

Menghantar kerja, kemudian memeriksa sehingga completed atau failed, atau sehingga masa tamat dicapai.

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

done.translations.de
done.usage.total_tokens

Kitar hayat kerja 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 kerja async (ringkasan)

1. Polling hantar dan lupa: jobs.create → pekerja anda memanggil jobs.get secara berkala sehingga completed atau failed.
2. Polling terbina dalam: jobs.translate. Semantik sama, dengan pollInterval, timeout, dan onProgress.

Payload besar dan terjemahan jangka panjang disyorkan 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.2

• Penyelenggaraan: URL asas API lalai ialah https://api.usepolylingo.com/v1.

0.1.0

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