Node.js SDK (polylingo)

Mteja rasmi wa TypeScript 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 Marejeleo ya API.

Ufungaji

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. Hakuna uthibitishaji unahitajika kwenye seva; mteja bado hutuma kichwa cha Authorization ikiwa kimewekwa.

Hurejesha { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages. Hurejesha 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; acha API itambue 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. Hurejesha matumizi ya mpango kwa funguo iliyothibitishwa.

const u = await client.usage()

Jobs (client.jobs)

client.jobs.create(params)

POST /jobs. Inaweka kazi isiyo ya moja kwa moja kwenye foleni na hurudisha 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. Huchunguza hali. Wakati status === 'completed', API hurudisha 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)

Hutuma kazi, kisha huchunguza hadi completed au failed, au hadi muda wa kusubiri umekamilika.

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,     // muda wa jumla wa 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.

Kushughulikia 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.

Mizigo mikubwa na tafsiri ndefu inapaswa 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 kama inavyohitajika (angalia dist/index.d.ts iliyochapishwa).

Changelog

0.1.2

• Matengenezo: URL ya msingi ya API ni https://api.usepolylingo.com/v1 kwa chaguo-msingi.

0.1.0

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