Node.js SDK (polylingo)

Client officiel TypeScript 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. Retourne la 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 ; omettre pour laisser l'API détecter automatiquement
  source: 'en',       // indice optionnel
  model: 'standard',  // optionnel : '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',    // optionnel
  model: 'standard', // optionnel
})

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

client.usage()

GET /usage. Retourne l'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 et 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) (confort)

Soumet un travail, puis interroge jusqu'à ce que ce soit completed ou failed, ou jusqu'à ce que le délai soit atteint.

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

done.translations.de
done.usage.total_tokens

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

Gestion des erreurs

Tous les échecs 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 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.2

• Maintenance : l'URL de base API par défaut est https://api.usepolylingo.com/v1.

0.1.0

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