Node.js SDK (polylingo)

PolyLingo REST API の公式 TypeScript クライアントです。ランタイムに 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 は 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, // ポーリング間隔（ミリ秒）、デフォルトは 5_000
  timeout: 600_000,     // ポーリングの**合計**ミリ秒予算、デフォルトは 20 分
  onProgress: (pos) => console.log(`Queue position: ${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.2

• メンテナンス: デフォルトの API ベース URL は https://api.usepolylingo.com/v1 です。

0.1.0

• 初期リリース: health, languages, translate, batch, usage, jobs.create, jobs.get, jobs.translate。