Node.js SDK (polylingo)

Client officiel TypeScript-first pour l'API REST PolyLingo. Il utilise le runtime fetch (Node.js 18+), est distribué en ESM et CJS, et n'a aucune dépendance à l'exécution au-delà de Node.

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

Pour les détails HTTP bruts, voir API reference.

Installation

npm install polylingo

Node.js : >= 18

Constructeur

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // requis
  baseURL: 'https://api.usepolylingo.com/v1', // optionnel ; c'est la valeur par défaut
  timeout: 120_000, // optionnel ; délai d'attente de la requête en millisecondes (par défaut 120_000)
})

Méthodes

client.health()

GET /health — pas d'authentification requise côté serveur ; le client envoie néanmoins l'en-tête Authorization si configuré.

Retourne { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — liste des langues supportées.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // optionnel — omis = détection automatique par l'API
  source: 'en',       // indice optionnel
  model: 'standard',  // optionnel : 'standard' | 'advanced'
})

r.translations.es // chaîne
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',    // optionnel
  model: 'standard', // optionnel
})

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

client.usage()

GET /usage — utilisation du plan pour la clé authentifiée.

const u = await client.usage()

Jobs — client.jobs

client.jobs.create(params)

POST /jobs — met en file d'attente un travail asynchrone. Résout avec le corps JSON 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 — interroge le statut. Lorsque status === 'completed', l'API retourne translations et usage au niveau supérieur de l'objet JSON (pas imbriqué sous result).

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

client.jobs.translate(params) — commodité

Soumet un travail, puis interroge jusqu'à ce qu'il soit completed ou failed, ou jusqu'à épuisement du budget d'interrogation.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms entre les interrogations ; défaut 5_000
  timeout: 600_000,     // budget **total** en ms pour l'interrogation ; défaut 20 minutes
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // optionnel ; appelé pendant la mise en file / le traitement
})

done.translations.de
done.usage.total_tokens

Le cycle de vie des jobs dans l'API utilise les statuts pending, processing, completed et failed.

Gestion des erreurs

Toutes les erreurs du SDK (sauf bugs) étendent PolyLingoError :

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

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

Modèle de jobs asynchrones (résumé)

1. Polling fire-and-forget : jobs.create → votre worker appelle jobs.get à intervalle régulier jusqu'à completed ou failed.
2. Polling intégré : jobs.translate — même sémantique, avec pollInterval, timeout et onProgress.

Les charges importantes et les traductions longues devraient préférer les jobs au translate synchrone pour éviter les timeouts HTTP.

TypeScript

Le package exporte des types pour les options, résultats et erreurs. Importez les types nommés depuis polylingo selon les besoins (voir dist/index.d.ts publié).

Journal des modifications

0.1.0

• Première version : health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.