Node.js SDK (polylingo)

Mteja rasmi wa TypeScript-first kwa PolyLingo REST API. Inatumia runtime fetch (Node.js 18+), hutolewa kama ESM na CJS, na haina mategemeo ya runtime zaidi ya Node.

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

Kwa maelezo ya HTTP ghafi, angalia Rejea ya API.

Usanidi

npm install polylingo

Node.js: >= 18

Muundaji

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // inahitajika
  baseURL: 'https://api.usepolylingo.com/v1', // hiari; hii ni chaguo-msingi
  timeout: 120_000, // hiari; muda wa kusubiri ombi kwa millisekunde (chaguo-msingi 120_000)
})

Mbinu

client.health()

GET /health — haitaji uthibitisho kwenye seva; mteja bado hutuma kichwa cha Authorization ikiwa kimewekwa.

Inarudisha { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — orodha ya lugha zinazotegemewa.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // hiari — ikiachwa = API itagundua moja kwa moja
  source: 'en',       // kidokezo hiari
  model: 'standard',  // hiari: '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',    // hiari
  model: 'standard', // hiari
})

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

client.usage()

GET /usage — matumizi ya mpango kwa funguo iliyothibitishwa.

const u = await client.usage()

Jobs — client.jobs

client.jobs.create(params)

POST /jobs — weka kazi isiyo ya moja kwa moja kwenye foleni. Inarudisha mwili wa JSON wa 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 — angalia hali. Wakati status === 'completed', API inarudisha translations na usage kwenye ngazi ya juu ya kitu cha JSON (si chini ya result).

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

client.jobs.translate(params) — urahisi

Inawasilisha kazi, kisha inachunguza hadi completed au failed, au hadi bajeti ya uchunguzi itakapokamilika.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms kati ya uchunguzi; chaguo-msingi 5_000
  timeout: 600_000,     // bajeti ya **jumla** ya ms kwa uchunguzi; chaguo-msingi dakika 20
  onProgress: (pos) => console.log(`Nafasi kwenye foleni: ${pos}`), // hiari; huitwa wakati iko kwenye foleni/inaendelea
})

done.translations.de
done.usage.total_tokens

Mzunguko wa maisha wa kazi kwenye API unatumia hali pending, processing, completed, na failed.

Usimamizi wa makosa

Mafanikio yote kutoka SDK (isipokuwa mende) yanapanua PolyLingoError:

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

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

Mfano wa kazi zisizo za moja kwa moja (muhtasari)

1. Polling ya fire-and-forget: jobs.create → mfanyakazi wako anaita jobs.get kwa vipindi hadi completed au failed.
2. Polling iliyojengwa ndani: jobs.translate — semantiki sawa, na pollInterval, timeout, na onProgress.

Vipakia vikubwa na tafsiri ndefu zinapaswa kutumia jobs badala ya translate ya sinkroni ili kuepuka muda wa kusubiri wa HTTP.

TypeScript

Kifurushi kinatoa aina za chaguzi, matokeo, na makosa. Ingiza aina zilizopewa majina kutoka polylingo inapohitajika (angalia dist/index.d.ts iliyochapishwa).

Mabadiliko

0.1.0

• Toleo la awali: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.