Node.js SDK (polylingo)

Officiel TypeScript-klient til PolyLingo REST API. Den bruger runtime fetch (Node.js 18+), leveres som ESM og CJS, og har ingen runtime-afhængigheder ud over Node.

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

For rå HTTP-detaljer, se API reference.

Installation

npm install polylingo

Node.js: >= 18

Konstruktor

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // påkrævet
  baseURL: 'https://api.usepolylingo.com/v1', // valgfrit; dette er standard
  timeout: 120_000, // valgfrit; timeout for forespørgsel i millisekunder (standard 120_000)
})

Metoder

client.health()

GET /health. Ingen autentificering kræves på serveren; klienten sender stadig Authorization header, hvis konfigureret.

Returnerer { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages. Returnerer listen over understøttede sprog.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // valgfrit; udelad for at lade API automatisk opdage
  source: 'en',       // valgfrit hint
  model: 'standard',  // valgfrit: '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',    // valgfrit
  model: 'standard', // valgfrit
})

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

client.usage()

GET /usage. Returnerer planforbrug for den autentificerede nøgle.

const u = await client.usage()

Jobs (client.jobs)

client.jobs.create(params)

POST /jobs. Sætter asynkront arbejde i kø og returnerer 202 JSON-krop (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. Poller status. Når status === 'completed', returnerer API translations og usage på øverste niveau af JSON-objektet (ikke under result).

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

client.jobs.translate(params) (bekvemmelighed)

Indsender et job, og poller derefter indtil completed eller failed, eller indtil timeout nås.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms mellem polls; standard 5_000
  timeout: 600_000,     // **total** ms budget for polling; standard 20 minutter
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // valgfrit; kaldt mens i kø/behandling
})

done.translations.de
done.usage.total_tokens

Joblivscyklussen på API bruger statusserne pending, processing, completed og failed.

Fejlhåndtering

Alle fejl fra SDK (undtagen bugs) nedarver PolyLingoError:

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

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

Async jobs mønster (resumé)

1. Fire-and-forget polling: jobs.create → din worker kalder jobs.get med jævne mellemrum indtil completed eller failed.
2. Indbygget polling: jobs.translate. Samme semantik, med pollInterval, timeout og onProgress.

Store payloads og langvarige oversættelser bør foretrække jobs frem for synkron translate for at undgå HTTP timeouts.

TypeScript

Pakken eksporterer typer for muligheder, resultater og fejl. Importer navngivne typer fra polylingo efter behov (se publiceret dist/index.d.ts).

Ændringslog

0.1.2

• Vedligeholdelse: standard API base URL er https://api.usepolylingo.com/v1.

0.1.0

• Første udgivelse: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.