SDK v0の連携を保守する

LingoDotDevEngineのヘルパーを理解し、移行時も入力、出力、バッチ処理、キャンセルの動作を維持する方法を確認します。

LingoDotDevEngineを使用するアプリケーションは、オブジェクトの翻訳だけでなく、リクエストの分割、配列の再構築、HTMLの解析などにも依存している場合があります。移行時には、これらの動作を確実に維持する必要があります。インポートを変更するだけでは、これらの処理を置き換えることはできません。

このリファレンスでは、lingo.dev 0.138.10を扱います。このバージョンのlingo.dev/sdkエントリーは、@lingo.dev/_sdk 0.17.3を再エクスポートします。呼び出し箇所を確認する間は、アプリケーションのLockfileに記録されたバージョンを維持してください。サーバー側のワークフローを新しく構築する場合は、JavaScript APIガイドを参照してください。

既存のオブジェクト翻訳呼び出し #

従来のサーバー側の呼び出し形式は、次のとおりです。

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

const apiKey = process.env.LINGO_API_KEY;
const engineId = process.env.LINGO_ENGINE_ID;
if (!apiKey || !engineId) throw new Error("Configure a key and localization engine ID");

const client = new LingoDotDevEngine({ apiKey, engineId });
const translated = await client.localizeObject(
  { greeting: "Welcome back" },
  { sourceLocale: "en", targetLocale: "es" },
);

このヘルパーは、翻訳済みのレコードを直接返します。認証情報はサーバー側で管理してください。ドキュメントジョブには、作成、開始、ダウンロードという独立したライフサイクルがあります。ジョブ作成時のレスポンスは、このヘルパーが返す翻訳済みレコードとは異なります。

コンストラクターとバッチ処理の制御 #

オプション従来の動作
apiKey必須の文字列。コンストラクターで検証されます。
apiUrlAPIのベースURLを上書きします。
engineId翻訳時に送信するローカライゼーションエンジンの指定。省略可能です。
batchSize既定値は25、最大値は250。
idealBatchItemSize既定値は250、最大値は2500。
maxRetries既定値は3。
retryDelayMs既定値は500ミリ秒。

バッチオプションが制御するのは、クライアント側でのチャンクの組み立てであり、アプリケーション全体の同時実行数ではありません。再試行ヘルパーは、待機時間を指数的に延ばしながらランダムな揺らぎを加え、ネットワーク障害や5xxエラーが発生したリクエストを再試行します。意図的な中断や通常の4xxレスポンスは、このヘルパーでは再試行されません。認識やアカウント照会などの操作には、それぞれ独自のリクエスト経路があります。すべてのメソッドに同じ再試行ポリシーが適用されるとは考えないでください。

ヘルパーの入力と戻り値 #

ヘルパー入出力仕様
localizeObject(object, params, progressCallback?, signal?)レコードを受け取り、翻訳済みのレコードを返します。
localizeText(text, params, progressCallback?, signal?)テキストをフィールドに格納し、翻訳済みの文字列を返します。
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)ロケールごとにテキストのリクエストを実行し、指定されたロケールの順序で文字列を返します。
localizeStringArray(strings, params)一時キーを使って文字列配列を再構築します。公開されたシグナルパラメーターはありません。
localizeChat(messages, params, progressCallback?, signal?){ name, text }メッセージ内のtextを翻訳し、メッセージの名前はそのまま保持します。
localizeHtml(html, params, progressCallback?, signal?)jsdomでHTMLを解析し、対象のコンテンツを翻訳して、結果をシリアライズします。
recognizeLocale(text, signal?)認識結果のロケール値を返します。
estimate(items, signal?){ targetLocale, sourceChars }の項目を受け取り、概算の合計とロケール別の費用を返します。
whoami(signal?)アカウント関連のリクエストが通常の失敗レスポンスを返した場合は、{ email, id }またはnullを返します。サーバーエラーでは例外が発生する場合があります。

共通の翻訳パラメーターは、sourceLocale(検出する場合はヌル値を指定可能)、targetLocale、省略可能なfast、ロケール別の参照データ、キーごとのヒント配列、filePath、triggerType(cliまたはci)です。ロケールは使用前に正規化されます。新しいリクエストスキーマに対応付ける際は、各入力の意味を維持してください。

進捗コールバックは、クライアント側で完了したチャンクについて、完了率や元のチャンク、処理済みのチャンクを報告します。永続性のあるバックグラウンドジョブの通知ではありません。AbortSignalはクライアント側の処理を停止しますが、サーバーがすでに受け付けた処理を取り消すことはできません。

HTMLの処理動作を明示的に維持する #

HTMLヘルパーは、scriptとstyleの外側にあるテキストノードに加え、meta.content、img.alt、input.placeholder、a.titleを翻訳します。ドキュメントの言語を翻訳先の言語に設定し、DOMをシリアライズします。すべての属性を翻訳するわけではなく、元のバイト列も保持しません。

このヘルパーは、動的なjsdomインポートの解決も含め、実際のサーバー実行環境でテストしてください。HTMLの呼び出しを別の変換処理に移行する前に、リンク、構造を表すマークアップ、対象の属性、シリアライズ後の出力を比較してください。構造化されたJSONリクエストだけでは、これらのHTML処理は実行されません。

ReplexicaEngineとLingoEngineは、互換性を保つためのエイリアスとしてLingoDotDevEngineを継承し、非推奨であることを示す警告を出力します。エイリアスの警告を解消しても、それは名前の変更にすぎず、動作の移行が完了したことにはなりません。

アプリケーションをドキュメントジョブに移行する #

新しい連携には、APIジョブのライフサイクルを使用してください。オブジェクトの内容をインラインのJSONドキュメントに格納してジョブを開始し、完了した翻訳先ごとに成果物をダウンロードします。アプリケーションが結果を受け入れるまでは、ジョブIDをソースのリビジョンとともに保持してください。

現在、テキストのフィールドへの格納、配列の順序、HTMLの解析、バッチ処理、進捗コールバックに依存しているアプリケーションの動作は、移行後も維持してください。ファイル翻訳には、対応するドキュメント形式を使用できます。通信方式を変更しても、クライアント側の変換や再試行が自動的に再現されるわけではありません。

アプリケーションのデータ保存処理を新しいフローに切り替える前に、得られるデータと失敗時の処理を比較してください。部分的な結果や順不同での完了については、ワークフローガイドで説明しています。