JavaScript SDK - Lingo.dev SDK

はじめに

Lingo.dev JavaScript SDKは、ウェブアプリケーション、Node.jsサーバー、フロントエンドフレームワークにリアルタイムAI駆動の翻訳機能を追加します。このSDKは、チャットメッセージ、ユーザーコメント、即時翻訳が必要なライブデータなどの動的コンテンツを処理します。

Lingo.dev CLIによる静的ファイルのローカライゼーションとは異なり、SDKはオンデマンドでコンテンツを処理するため、コンテンツが常に変化するチャットアプリケーション、メールクライアント、ソーシャルメディアツールに最適です。

インストール

npm install lingo.dev

基本設定

SDKはLingo.devのAPIキーが必要です。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

テキスト翻訳

シンプルなテキスト文字列を対象言語に翻訳します。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const result = await lingoDotDev.localizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// 出力: "¡Hola Mundo!"

オブジェクト翻訳

構造を保持しながらネストされたオブジェクトを翻訳します。SDKはすべての文字列値を再帰的に処理します。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const content = {
  greeting: "Hello",
  farewell: "Goodbye",
  message: "Welcome to our platform",
};

const translated = await lingoDotDev.localizeObject(content, {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(translated);
// 出力: { greeting: "Hola", farewell: "Adiós", message: "Bienvenido a nuestra plataforma" }

複数言語へのバッチ翻訳

1回の呼び出しで複数の対象言語にコンテンツを翻訳します。対象ロケールごとに1つの結果を含む配列を返します。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const results = await lingoDotDev.batchLocalizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
});
console.log(results);
// 出力: ['¡Hola Mundo!', 'Bonjour le monde!', 'Hallo Welt!']

チャット翻訳

話者名を保持しながらチャットメッセージを翻訳します。各メッセージには「name」と「text」の両方のフィールドが必要です。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const conversation = [
  { name: "Alice", text: "Hello!" },
  { name: "Bob", text: "How are you?" },
  { name: "Alice", text: "I'm doing well, thanks!" },
];

const translated = await lingoDotDev.localizeChat(conversation, {
  sourceLocale: "en",
  targetLocale: "es",
});

for (const message of translated) {
  console.log(`${message.name}: ${message.text}`);
}
// Output:
// Alice: ¡Hola!
// Bob: ¿Cómo estás?
// Alice: ¡Me va bien, gracias!

HTML翻訳

マークアップを保持しながらHTMLを翻訳します。すべてのタグ、属性、構造を維持しながらテキストコンテンツのみを翻訳します。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const html = "<div>Hello <strong>world</strong></div>";

const translated = await lingoDotDev.localizeHtml(html, {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(translated);
// Output: "<div>Hola <strong>mundo</strong></div>"

進捗追跡

コールバックを使用して翻訳の進捗状況を監視します。大規模な翻訳操作中にUIを更新するのに役立ちます。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const largeObject = {
  page1: "Welcome to our application",
  page2: "This is the second page",
  page3: "Here is more content",
  page4: "Final page of content",
};

await lingoDotDev.localizeObject(
  largeObject,
  { sourceLocale: "en", targetLocale: "es" },
  (progress) => {
    console.log(`Translation progress: ${progress}%`);
  },
);
// Output:
// Translation progress: 25%
// Translation progress: 50%
// Translation progress: 75%
// Translation progress: 100%

翻訳パラメータ

時間的制約のあるアプリケーションにおける速度と品質管理のトレードオフ。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const result = await lingoDotDev.localizeText("Hello world", {
  sourceLocale: "en",
  targetLocale: "es",
  fast: true, // 品質より速度を優先
});
console.log(result);
// 出力: "Hola mundo"

設定

バッチ処理の動作を制御します。SDKは項目数と単語数の制約に基づいて大きなペイロードを分割します。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
  batchSize: 100, // APIリクエストあたりの最大項目数（デフォルト: 50、最大: 250）
  idealBatchItemSize: 1000, // バッチあたりの目標単語数（デフォルト: 500、最大: 2500）
});

const result = await lingoDotDev.localizeText("Configuration test", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// 出力: "Prueba de configuración"

言語検出

テキスト文字列の言語を検出します。検出には処理時間がかかるため、ソース言語が不明な場合にのみ使用してください。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const locale = await lingoDotDev.recognizeLocale("Bonjour le monde");
console.log(locale);
// 出力: 'fr'

自動検出と併用する例：

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const result = await lingoDotDev.localizeText("Bonjour le monde", {
  sourceLocale: null, // 自動検出
  targetLocale: "en",
});
console.log(result);
// 出力: "Hello world"

エラー処理

SDKにはネットワーク問題に対する自動リトライ機能が含まれています。その他の障害に対してはアプリケーションレベルのエラー処理を実装してください。

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

try {
  const result = await lingoDotDev.localizeText("Hello", {
    sourceLocale: "en",
    targetLocale: "es",
  });
  console.log(result);
} catch (error) {
  console.error("Translation failed:", error.message);
  // 適切にエラーを処理
}