Node.js SDK (polylingo)

PolyLingo REST API için resmi TypeScript-öncelikli istemci. Çalışma zamanı fetch (Node.js 18+) kullanır, ESM ve CJS olarak paketlenir ve Node dışında çalışma zamanı bağımlılığı yoktur.

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

Ham HTTP detayları için bkz. API referansı.

Kurulum

npm install polylingo

Node.js: >= 18

Yapıcı

import PolyLingo from 'polylingo'

const client = new PolyLingo({
  apiKey: process.env.POLYLINGO_API_KEY!, // zorunlu
  baseURL: 'https://api.usepolylingo.com/v1', // isteğe bağlı; varsayılan bu
  timeout: 120_000, // isteğe bağlı; istek zaman aşımı milisaniye cinsinden (varsayılan 120_000)
})

Metodlar

client.health()

GET /health — sunucuda kimlik doğrulama gerekmez; istemci yapılandırılmışsa yine de Authorization başlığını gönderir.

{ status, timestamp } döner.

const h = await client.health()

client.languages()

GET /languages — desteklenen dil listesi.

const { languages } = await client.languages()

client.translate(params)

POST /translate

const r = await client.translate({
  content: '# Hello',
  targets: ['es', 'fr'],
  format: 'markdown', // isteğe bağlı — API'de otomatik algılama için atlanabilir
  source: 'en',       // isteğe bağlı ipucu
  model: 'standard',  // isteğe bağlı: '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',    // isteğe bağlı
  model: 'standard', // isteğe bağlı
})

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

client.usage()

GET /usage — kimlik doğrulanmış anahtar için plan kullanımı.

const u = await client.usage()

İşler — client.jobs

client.jobs.create(params)

POST /jobs — asenkron iş kuyruğa ekle. 202 JSON gövdesiyle çözülür (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 — durum sorgula. status === 'completed' olduğunda, API JSON nesnesinin en üst seviyesinde translations ve usage döner (result altında değil).

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

client.jobs.translate(params) — kolaylık

Bir iş gönderir, sonra completed veya failed olana ya da sorgulama bütçesi tükenene kadar sorgular.

const done = await client.jobs.translate({
  content: longMarkdown,
  targets: ['de', 'fr', 'es'],
  format: 'markdown',
  pollInterval: 10_000, // sorgular arası ms; varsayılan 5_000
  timeout: 600_000,     // sorgulama için **toplam** ms bütçesi; varsayılan 20 dakika
  onProgress: (pos) => console.log(`Kuyruk pozisyonu: ${pos}`), // isteğe bağlı; kuyrukta/işlenirken çağrılır
})

done.translations.de
done.usage.total_tokens

API'deki iş yaşam döngüsü pending, processing, completed ve failed durumlarını kullanır.

Hata yönetimi

SDK'dan gelen tüm hatalar (hatalar hariç) PolyLingoError sınıfını genişletir:

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

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

Asenkron işler deseni (özet)

1. Gönder ve unut sorgulama: jobs.create → işçi belirli aralıklarla jobs.get çağırır, completed veya failed olana kadar.
2. Yerleşik sorgulama: jobs.translate — aynı anlam, pollInterval, timeout ve onProgress ile.

Büyük yükler ve uzun süren çeviriler, HTTP zaman aşımından kaçınmak için eşzamanlı translate yerine işleri tercih etmelidir.

TypeScript

Paket, seçenekler, sonuçlar ve hatalar için tipler ihraç eder. Gerekli named tipleri polylingodan içe aktarın (yayınlanan dist/index.d.ts dosyasına bakınız).

Değişiklikler

0.1.0

• İlk sürüm: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.