Node.js SDK (polylingo)

PolyLingo REST API için resmi TypeScript istemcisi. Çalışma zamanı olarak 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 listesini döner.

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 otomatik algılasın diye 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ını döner.

const u = await client.usage()

İşler (client.jobs)

client.jobs.create(params)

POST /jobs. Asenkron iş kuyruğa alınır ve 202 JSON gövdesi (job_id, status, created_at, …) ile çözülür.

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. Durumu sorgular. status === 'completed' olduğunda API JSON nesnesinin en üst seviyesinde translations ve usage döner (sonuç 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 zaman aşımı olana 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 üzerindeki 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ını önlemek için senkron translate yerine işleri tercih etmelidir.

TypeScript

Paket seçenekler, sonuçlar ve hatalar için tipler dışa aktarır. Gerekli tipleri polylingo'dan isimli olarak içe aktarın (yayınlanan dist/index.d.ts dosyasına bakınız).

Değişiklikler

0.1.2

• Bakım: varsayılan API temel URL'si https://api.usepolylingo.com/v1 olarak ayarlandı.

0.1.0

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