エンジン提案API

翻訳に関するフィードバックは、ダッシュボード上のクリックとして届くことはほとんどありません。実際には、自社のサポートツールに残された一文だったり、レビュー担当者からのメモだったり、QAキューの1行だったりします。たとえば「製品名は翻訳しないで」「ドイツ語では敬体を使って」のようなものです。Engine Suggestions API は、そうした自由記述のテキストを、コードからエンジンの変更案へと変換します。フィードバックをテキストで送ると、プラットフォームがその内容をもとに判断し、エンジンの用語集、指示、またはブランドボイスに対する具体的で構造化された編集案を返します。あとは、それをあなたが適用するだけです。

これは、ダッシュボード機能に対応するプログラム向けの仕組みです。ダッシュボードでは、AI評価者 が翻訳を低く採点したときに提案が自動生成されますが、こちらではそのシグナルを あなた自身 がテキストで与えます。どちらの場合も出力は同じで、レビューして適用できる保留中の提案が得られます。

流れは大きく2つに分かれます。生成 は非同期です。フィードバックを渡すと、プラットフォームがバックグラウンドで内容を判断し、保留中の提案をエンジン上に作成します。レビュー は同期です。保留中の提案を一覧し、それぞれの提案内容を確認して、適用または却下します。このページではその両方を扱います。ダッシュボードでの体験、つまり低いレビュースコアからの自動生成、Suggestions タブ、通知については、Engine Suggestions を参照してください。

フィードバックから生成する#

POST /engines/:id/suggestions/from-text

エンジンのどこに問題があるのかを、プレーンテキストで送信します。プラットフォームは そのテキスト と現在のエンジン設定をもとに判断し、最小単位の編集案を提案します。エンジンにすでに存在する内容を重ねて提案することはありません。生成は非同期で実行されるため、この呼び出しが返るのは提案の準備完了時ではなく、処理が受け付けられた時点です。

const response = await fetch(
  `https://api.lingo.dev/engines/${engineId}/suggestions/from-text`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.LINGO_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      text: "Our German (de-DE) translations keep using the informal 'du'. For our B2B audience they must always use the formal 'Sie'.",
    }),
  },
);

const { enqueued } = await response.json();
console.log(enqueued); // true – generation accepted, running in the background

{ "enqueued": true }

enqueued: true が意味するのは、プラットフォームが処理を受け付けたということだけで、まだ提案が存在するとは限りません。生成は1回のバックグラウンド処理で行われ、テキストを読み取り、設定を踏まえて判断し、既存の内容との重複を除外したうえで、提案した内容を保存します。結果として、何も提案されないこともあります。たとえばフィードバックが曖昧だったり、エンジンがすでにその内容をカバーしていたりする場合です。結果を確認するには、少し待ってから エンジンの提案を一覧表示する を実行してください。

保留中の提案を一覧表示する#

GET /engines/:id/suggestions

エンジンの提案を返します。対象は、テキストからの生成、手動ボタンによる生成、低いレビュースコアからの自動生成など、あらゆる生成実行の結果です。各エントリには、提案された編集内容とその理由が含まれます。

[
  {
    "id": "egs_A1b2C3d4E5f6G7h8",
    "ownerOrganizationId": "org_X1y2Z3a4B5c6D7e8",
    "ownerEngineId": "eng_X1y2Z3a4B5c6D7e8",
    "actionType": "add_instruction",
    "targetKind": "instruction",
    "targetId": null,
    "targetLocale": "de-DE",
    "payload": { "instruction": "Use the formal 'Sie' form in all German translations; never use the informal 'du'." },
    "reasoning": "Feedback states the B2B audience requires formal address, but the engine has no instruction enforcing it.",
    "sourceReviewLogIds": [],
    "status": "pending",
    "appliedTargetId": null,
    "createdAt": "2026-06-18T10:30:00.000Z"
  }
]

payload があるからこそ、適用は軽く済みます。提案される変更は生成時点で完全に構造化されているため、適用は単なる書き込みであり、AIをもう一度回す処理ではありません。判断するのはあなたであり、プラットフォームが再度推論することはありません。

提案を適用する#

POST /engine-suggestions/:id/apply

提案された変更をエンジンに書き込み、その提案を applied としてマークします。これは、一覧ですでに確認した payload をそのまま書き込む決定的な処理です。2回目のAI呼び出しはないため、レビューした内容がそのまま反映されます。add_* 提案は新しい用語集項目、指示、またはブランドボイスを作成し、update_* 提案は targetId で指定された既存エントリを変更します。

const response = await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/apply`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);

const applied = await response.json();
console.log(applied.status);          // "applied"
console.log(applied.appliedTargetId); // "ins_…" – the instruction it just created

レスポンスでは、applied 状態になった提案が返ります。このとき appliedTargetId は、実際に作成または更新されたエンジンエントリを指すようになります。そのエントリは以後、通常の用語集項目、指示、またはブランドボイスとして扱えます。ほかのエントリと同じように、開いて、編集して、削除できます。

提案を却下する#

POST /engine-suggestions/:id/dismiss

不要な提案を破棄し、dismissed としてマークします。エンジンには何も変更されません。提案が自社製品に合わないときに使ってください。エンジンはそのままで、その提案は保留中一覧にも表示されなくなります。

await fetch(
  `https://api.lingo.dev/engine-suggestions/${suggestionId}/dismiss`,
  {
    method: "POST",
    headers: { "X-API-Key": process.env.LINGO_API_KEY },
  },
);
// The suggestion is now "dismissed"; nothing was written to the engine.

一連の流れ#

この4つのエンドポイントで、コードだけですべてを回せる1つのサイクルが完成します。フィードバックを送り、提案内容を確認し、納得した編集だけを反映できます。

次のステップ#