Node.js SDK (polylingo)

PolyLingo REST API를 위한 공식 TypeScript 우선 클라이언트입니다. 런타임 fetch (Node.js 18+)를 사용하며, ESM 및 CJS로 배포되고 Node 외에 런타임 의존성이 없습니다.

• npm: polylingo
• 소스: UsePolyLingo/polylingo-node

원시 HTTP 세부사항은 API 참조를 참조하세요.

설치

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는 JSON 객체 최상위에 translations와 usage를 반환합니다 (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, // 폴링 간격(ms); 기본 5_000
  timeout: 600_000,     // 폴링 총 예산(ms); 기본 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 포함

큰 페이로드와 장시간 번역은 HTTP 타임아웃을 피하기 위해 동기 translate 대신 jobs 사용을 권장합니다.

TypeScript

패키지는 옵션, 결과, 오류 타입을 내보냅니다. 필요에 따라 polylingo에서 명명된 타입을 가져오세요 (dist/index.d.ts 참조).

변경 로그

0.1.0

• 초기 릴리스: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate.