Node.js SDK (polylingo)

Офіційний клієнт PolyLingo REST API з пріоритетом TypeScript. Використовує runtime fetch (Node.js 18+), постачається як ESM та CJS, і не має залежностей під час виконання поза Node.

• npm: polylingo
• Джерело: UsePolyLingo/polylingo-node

Для деталей сирого HTTP див. API reference.

Встановлення

npm install polylingo

Node.js: >= 18

Конструктор

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // обов’язково
  baseURL: 'https://api.usepolylingo.com/v1', // необов’язково; це за замовчуванням
  timeout: 120_000, // необов’язково; таймаут запиту в мілісекундах (за замовчуванням 120_000)
})

Методи

client.health()

GET /health — на сервері автентифікація не потрібна; клієнт все одно надсилає заголовок Authorization, якщо налаштовано.

Повертає { status, timestamp }.

const h = await client.health()

client.languages()

GET /languages — список підтримуваних мов.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // необов’язково — пропущено = авто-визначення на API
  source: 'en',       // необов’язкова підказка
  model: 'standard',  // необов’язково: 'standard' | 'advanced'
})

r.translations.es // рядок
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',    // необов’язково
  model: 'standard', // необов’язково
})

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

client.usage()

GET /usage — використання плану для автентифікованого ключа.

const u = await client.usage()

Роботи — client.jobs

client.jobs.create(params)

POST /jobs — поставити асинхронну роботу в чергу. Повертає 202 JSON тіло (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 — опитування статусу. Коли status === 'completed', API повертає translations і usage на верхньому рівні JSON об’єкта (не вкладені в result).

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

client.jobs.translate(params) — зручність

Надсилає роботу, потім опитує, доки не буде completed або failed, або поки не вичерпається бюджет опитування.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // мс між опитуваннями; за замовчуванням 5_000
  timeout: 600_000,     // **загальний** бюджет мс для опитування; за замовчуванням 20 хвилин
  onProgress: (pos) => console.log(`Позиція в черзі: ${pos}`), // необов’язково; викликається під час черги/обробки
})

done.translations.de
done.usage.total_tokens

Життєвий цикл роботи в API використовує статуси pending, processing, completed і failed.

Обробка помилок

Всі помилки SDK (крім багів) розширюють PolyLingoError:

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

try {
  await client.translate({ content: 'Hi', targets: ['es'] })
} catch (e) {
  if (e instanceof AuthError) { /* недійсний ключ */ }
  else if (e instanceof RateLimitError) { /* e.retryAfter */ }
  else if (e instanceof JobFailedError) { /* e.jobId */ }
  else if (e instanceof PolyLingoError) { /* e.status, e.error */ }
}

Шаблон асинхронних робіт (резюме)

1. Опитування "вистрілив і забув": jobs.create → ваш робітник викликає jobs.get з інтервалом, доки не буде completed або failed.
2. Вбудоване опитування: jobs.translate — ті ж семантики, з pollInterval, timeout і onProgress.

Великі навантаження та тривалі переклади слід віддавати перевагу роботам замість синхронного translate, щоб уникнути таймаутів HTTP.

TypeScript

Пакет експортує типи для опцій, результатів і помилок. Імпортуйте іменовані типи з polylingo за потребою (див. опублікований dist/index.d.ts).

Журнал змін

0.1.0

• Початковий реліз: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.