Node.js SDK (polylingo)

Virallinen TypeScript-asiakas PolyLingo REST API:lle. Käyttää runtimea fetch (Node.js 18+), toimitetaan ESM- ja CJS-muodossa, eikä sillä ole muita ajonaikaisia riippuvuuksia kuin Node.

• npm: polylingo
• Lähdekoodi: UsePolyLingo/polylingo-node

Raakaa HTTP-tietoa varten katso API reference.

Asennus

npm install polylingo

Node.js: >= 18

Konstruktor

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // pakollinen
  baseURL: 'https://api.usepolylingo.com/v1', // valinnainen; tämä on oletus
  timeout: 120_000, // valinnainen; pyynnön aikakatkaisu millisekunteina (oletus 120_000)
})

Metodit

client.health()

GET /health. Ei vaadi autentikointia palvelimella; asiakas lähettää silti Authorization-otsikon, jos se on määritetty.

Palauttaa { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages. Palauttaa tuettujen kielten listan.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // valinnainen; jätä pois, jotta API tunnistaa automaattisesti
  source: 'en',       // valinnainen vihje
  model: 'standard',  // valinnainen: 'standard' | 'advanced'
})

r.translations.es // merkkijono
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',    // valinnainen
  model: 'standard', // valinnainen
})

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

client.usage()

GET /usage. Palauttaa suunnitelman käytön todennetulle avaimelle.

const u = await client.usage()

Työt (client.jobs)

client.jobs.create(params)

POST /jobs. Lisää asynkronisen työn jonoon ja palauttaa 202 JSON-vastauksen (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. Kysyy tilaa. Kun status === 'completed', API palauttaa translations ja usage JSON-objektin ylimmäisellä tasolla (ei result-kohdassa).

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

client.jobs.translate(params) (kätevyys)

Lähettää työn, sitten kysyy tilaa toistuvasti kunnes completed tai failed, tai kunnes aikakatkaisu saavutetaan.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms kyselyjen välillä; oletus 5_000
  timeout: 600_000,     // **kokonais** ms-aikabudjetti kyselyyn; oletus 20 minuuttia
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // valinnainen; kutsutaan jonossa/työstössä ollessa
})

done.translations.de
done.usage.total_tokens

Työn elinkaari API:ssa käyttää tiloja pending, processing, completed ja failed.

Virheenkäsittely

Kaikki SDK:n virheet (paitsi bugit) periytyvät PolyLingoError-luokasta:

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

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

Asynkronisten töiden malli (yhteenveto)

1. Fire-and-forget-kysely: jobs.create → työntekijäsi kutsuu jobs.get säännöllisesti kunnes tila on completed tai failed.
2. Sisäänrakennettu kysely: jobs.translate. Samat merkitykset, mukana pollInterval, timeout ja onProgress.

Suuret kuormat ja pitkät käännökset kannattaa tehdä töinä synkronisen translate-kutsun sijaan HTTP-aikakatkosten välttämiseksi.

TypeScript

Paketti vie tyyppejä vaihtoehdoille, tuloksille ja virheille. Tuo nimettyjä tyyppejä polylingo-kirjastosta tarpeen mukaan (katso julkaistu dist/index.d.ts).

Muutokset

0.1.2

• Ylläpito: oletus API base URL on https://api.usepolylingo.com/v1.

0.1.0

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