エンジンの提案API

フィードバックから提案を生成し、変更内容を確認したうえで、適用または却下を明示的に選択します。

エンジンの提案では、用語集の用語、ルール、ブランドボイスのバリエーションに対する変更を提案します。適用する前に、提案内容と適用先をレビューしてください。生成すると提案がキューに追加され、適用するとエンジンの指針が変更されます。

エンジンの提案は、Enterpriseプランの機能として記載されています。呼び出し元には、エンジンへのアクセス権に加え、該当する提案操作の権限も必要です。ダッシュボードでの操作手順は、キューの提案をご覧ください。

以下のすべてのルートで、https://api.lingo.devとAPI認証を使用します。

生成をリクエストする #

エンジンに蓄積されたフィードバックから提案を生成します。

http
POST /v2/engines/:engineId/engine-suggestions/generate
X-API-Key: YOUR_API_KEY

このリクエストに本文はありません。フィードバックを直接指定するには、次のようにします。

http
POST /v2/engines/:engineId/engine-suggestions/from-text
Content-Type: application/json
X-API-Key: YOUR_API_KEY
json
{
  "text": "In German account settings, use Abonnement for subscription. Avoid Mitgliedschaft for this product feature."
}

textには空白以外の文字を含め、全体を10,000文字以内にする必要があります。このモードでは、指定したフィードバック自体から提案を生成するため、修正したい内容と対象の言語を含めてください。

どちらのルートも、次の内容を含むHTTP 200を返します。

json
{ "enqueued": true }

このレスポンスはキューへの送信を確認するもので、生成の完了を示すものではありません。処理後に、エンジンの保留中の提案を一覧取得してください。有用な変更がない場合は、提案が生成されないこともあります。リクエスト直後の一覧が空でも、リクエストが失敗したとは限りません。

提案を一覧取得する #

http
GET /v2/organizations/:orgId/engine-suggestions?engineIds=YOUR_ENGINE_ID&statuses=Pending&limit=25
クエリパラメーター説明
engineIds指定したエンジンに絞り込みます。
targetLocalesロケールの適用範囲。すべてのロケールに適用される指針を示す*も含まれます。
statusesPending、Applied、またはDismissed。既定値はPendingです。
ids指定した提案IDを取得します。
limit1~100の整数。既定値は25です。
cursor内部構造を解釈せずに使用するページネーションカーソル。

複数の値を指定する場合は、配列パラメーターを繰り返し指定します。レスポンスにはdataとmeta.nextCursorが含まれます。nextCursorがnullになるまで、同じフィルターで取得を続けてください。

各提案には、次の情報が含まれます。

フィールド説明
id, organizationId, engineId提案の識別情報と所有者情報。
targetLocale提案された変更の適用対象となるロケールの範囲。
change型を持つ変更内容。詳細は後述します。
reasoning提案の説明。
sources評価機能による評価、人による編集、作業項目など、根拠となる情報への参照。
statustypeがPending、Applied、またはDismissedであるオブジェクト。
destination変更の適用先となる指針セット。取得できない場合はnull。
createdAt, updatedAtISO形式のタイムスタンプ。

適用先には、kind(Glossary、Ruleset、またはBrandVoice)、ヌル値を許容するid、name、willCreateが含まれます。適用によって指針セットが作成されるかどうかは、willCreateで確認してください。適用済みの状態には、at、ヌル値を許容するby、ヌル値を許容するtargetが含まれます。システムによって却下された提案には、reasonが含まれることがあります。

変更内容を確認する #

change.type内容
AddGlossaryTermsourceLocale、sourceText、targetLocale、targetText、ヌル値を許容するdescription、nonTranslatable。
UpdateGlossaryTermtermId、ヌル値を許容するglossaryId、指定された置換用フィールド。
AddRulename、text、targetLocale。
UpdateRuleruleIdと、指定されたname、text、またはtargetLocale。
AddBrandVoiceVariationtargetLocaleとtext。
UpdateBrandVoiceVariationvariationIdと、指定されたtargetLocaleまたはtext。

更新の提案には、変更するフィールドのみが含まれます。広範囲に及ぶ変更を適用する前に、対象のレコードと、その指針セットの共有状況を確認してください。

適用または却下する #

http
POST /v2/engine-suggestions/:id/apply
http
POST /v2/engine-suggestions/:id/dismiss

どちらのリクエストにも本文はなく、更新後の提案が返されます。適用または却下できるのは、保留中の提案のみです。適用すると提案された指針が書き込まれ、却下すると指針は変更されません。

対象が変更された、または存在しなくなった場合、適用時にEngineSuggestionConflictsまたはEngineSuggestionTargetGoneが返されることがあります。修正方法を選ぶ前に、提案とその対象を再取得してください。すでに判断済みの提案に再度判断を行うと、EngineSuggestionNotPendingが返されます。レスポンスから結果を判断できない場合は、むやみに書き込みを繰り返さず、提案の状態を確認してください。

複数の提案をまとめて判断する #

次の宛先に、ポストリクエストで{ "ids": ["FIRST_ID", "SECOND_ID"] }を送信します。

  • /v2/engine-suggestions/apply-many:重複しないIDを1~25件。
  • /v2/engine-suggestions/dismiss-many:重複しないIDを1~1,000件。

適用ではappliedとfailedが、却下ではdismissedとfailedが返されます。失敗した各項目には、idと名前付きのerrorが含まれます。HTTPの成功レスポンスにも、個別の処理の失敗が含まれる場合があります。ほかの項目が失敗しても、成功した項目の結果は保持されるため、各結果を個別に処理してください。

更新した指針を使用する #

適用後は、エンジンの用語集、ルール、ブランドボイスを確認し、代表的なコンテンツで試してください。新しいジョブを開始する前に、採用する指針を適用してください。既存の翻訳を更新するには、対象のコンテンツを明示的に選択してリフレッシュをリクエストします。指針を適用するだけでは、再翻訳のリクエストにはなりません。