Node.js SDK (polylingo)

Offizieller TypeScript-Client für die PolyLingo REST API. Verwendet das Runtime-fetch (Node.js 18+), wird als ESM und CJS ausgeliefert und hat keine Laufzeitabhängigkeiten außer Node.

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

Für rohe HTTP-Details siehe API reference.

Installation

npm install polylingo

Node.js: >= 18

Konstruktor

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // erforderlich
  baseURL: 'https://api.usepolylingo.com/v1', // optional; dies ist der Standard
  timeout: 120_000, // optional; Timeout für Anfragen in Millisekunden (Standard 120_000)
})

Methoden

client.health()

GET /health. Keine Authentifizierung auf dem Server erforderlich; der Client sendet dennoch den Authorization-Header, falls konfiguriert.

Gibt { status, timestamp } zurück.

const h = await client.health()

client.languages()

GET /languages. Gibt die Liste der unterstützten Sprachen zurück.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // optional; weglassen, damit die API automatisch erkennt
  source: 'en',       // optionaler Hinweis
  model: 'standard',  // optional: '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',    // optional
  model: 'standard', // optional
})

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

client.usage()

GET /usage. Gibt die Plan-Nutzung für den authentifizierten Schlüssel zurück.

const u = await client.usage()

Jobs (client.jobs)

client.jobs.create(params)

POST /jobs. Fügt asynchrone Arbeit in die Warteschlange ein und gibt den JSON-Body mit Status 202 zurück (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. Fragt den Status ab. Wenn status === 'completed', gibt die API translations und usage auf der obersten Ebene des JSON-Objekts zurück (nicht unter result).

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

client.jobs.translate(params) (Bequemlichkeit)

Sendet einen Job und fragt dann ab, bis completed oder failed erreicht ist oder das Timeout eintritt.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms zwischen Abfragen; Standard 5_000
  timeout: 600_000,     // **gesamt** ms Budget für Abfragen; Standard 20 Minuten
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // optional; wird während Warteschlange/Verarbeitung aufgerufen
})

done.translations.de
done.usage.total_tokens

Der Lebenszyklus eines Jobs in der API verwendet die Status pending, processing, completed und failed.

Fehlerbehandlung

Alle Fehler vom SDK (außer Bugs) erben von PolyLingoError:

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

try {
  await client.translate({ content: 'Hi', targets: ['es'] })
} catch (e) {
  if (e instanceof AuthError) { /* ungültiger Schlüssel */ }
  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-Muster (Zusammenfassung)

1. Fire-and-forget-Polling: jobs.create → Ihr Worker ruft jobs.get in Intervallen auf, bis completed oder failed erreicht ist.
2. Eingebautes Polling: jobs.translate. Gleiche Semantik, mit pollInterval, timeout und onProgress.

Große Nutzlasten und lang laufende Übersetzungen sollten Jobs gegenüber synchronem translate bevorzugen, um HTTP-Timeouts zu vermeiden.

TypeScript

Das Paket exportiert Typen für Optionen, Ergebnisse und Fehler. Importieren Sie benannte Typen aus polylingo nach Bedarf (siehe veröffentlichtes dist/index.d.ts).

Änderungsprotokoll

0.1.2

• Wartung: Standard-API-Basis-URL ist https://api.usepolylingo.com/v1.

0.1.0

• Erste Veröffentlichung: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.