Node.js SDK (polylingo)

Cliente oficial TypeScript-first para la API REST de PolyLingo. Utiliza el runtime fetch (Node.js 18+), se distribuye como ESM y CJS, y no tiene dependencias en tiempo de ejecución más allá de Node.

• npm: polylingo
• Código fuente: UsePolyLingo/polylingo-node

Para detalles HTTP en bruto, vea API reference.

Instalación

npm install polylingo

Node.js: >= 18

Constructor

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // requerido
  baseURL: 'https://api.usepolylingo.com/v1', // opcional; este es el valor predeterminado
  timeout: 120_000, // opcional; tiempo de espera de la solicitud en milisegundos (predeterminado 120_000)
})

Métodos

client.health()

GET /health — no requiere autenticación en el servidor; el cliente aún envía el encabezado Authorization si está configurado.

Devuelve { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — lista de idiomas soportados.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // opcional — omitido = detección automática en la API
  source: 'en',       // pista opcional
  model: 'standard',  // opcional: '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',    // opcional
  model: 'standard', // opcional
})

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

client.usage()

GET /usage — uso del plan para la clave autenticada.

const u = await client.usage()

Trabajos — client.jobs

client.jobs.create(params)

POST /jobs — encola trabajo asíncrono. Resuelve con el cuerpo 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 — consulta el estado. Cuando status === 'completed', la API devuelve translations y usage en el nivel superior del objeto JSON (no anidado bajo result).

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

client.jobs.translate(params) — conveniencia

Envía un trabajo, luego consulta hasta que esté completed o failed, o hasta que se agote el presupuesto de consulta.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // ms entre consultas; predeterminado 5_000
  timeout: 600_000,     // presupuesto **total** en ms para consultas; predeterminado 20 minutos
  onProgress: (pos) => console.log(`Queue position: ${pos}`), // opcional; llamado mientras está en cola/procesando
})

done.translations.de
done.usage.total_tokens

El ciclo de vida del trabajo en la API usa los estados pending, processing, completed y failed.

Manejo de errores

Todas las fallas del SDK (excepto errores de bugs) extienden PolyLingoError:

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

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

Patrón de trabajos asíncronos (resumen)

1. Polling fire-and-forget: jobs.create → tu trabajador llama a jobs.get en intervalos hasta completed o failed.
2. Polling incorporado: jobs.translate — misma semántica, con pollInterval, timeout y onProgress.

Las cargas grandes y traducciones de larga duración deberían preferir trabajos sobre translate síncrono para evitar tiempos de espera HTTP.

TypeScript

El paquete exporta tipos para opciones, resultados y errores. Importa tipos nombrados desde polylingo según sea necesario (ver dist/index.d.ts publicado).

Registro de cambios

0.1.0

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