これからローカライゼーションエンジンを立ち上げるとします。本当に良い翻訳を生むのは、何も入っていない空のエンジンではありません。ブランドボイス、用語集、指示が入ったエンジンです。だからこそ、すべての翻訳が自社プロダクトらしいトーンになり、すでに決めた用語が勝手に崩されることもありません。
しかも、その知識はたいていエンジンより先に存在しています。ブランドガイドラインのページ、スタイルガイド、用語集シート、昔翻訳者に渡したルール集。エンジンを手作業で作るとなると、それらを読み込み、ブランドボイス、用語集、指示のレコードとして1つずつ入れ直すことになります。始めやすい一方で、途中で手が止まりやすい、地味で骨の折れる作業です。
そのギャップを埋めるのが非同期プロビジョニングAPIです。すでにあるものを、そのまま渡すだけ。 リンクと生テキストを1回のリクエストでPOSTすると、エンジンIDがすぐ返り、AIエージェントがソースをクロールして、ブランドボイス、用語集項目、指示を抽出し、見つかったものから順に新しいエンジンへ反映していきます。エンジンはIDを受け取った瞬間から使い始められ、設定はジョブの進行に合わせて埋まっていきます。
このページの内容
課題#
ローカライゼーションエンジンの価値は、設定で決まります。モデルを選べば翻訳自体はできますが、その翻訳をすでにあるプロダクトの話し方に合わせるのは、ブランドボイス、用語集項目、指示です。たとえば、選んだ丁寧さ、絶対に翻訳しないプロダクト名、常に使う日付形式などです。これらは、もともと手作業で1つずつ作るはずだった ブランドボイス、用語集項目、指示 という、エンジン 上の基本要素そのものです。
問題は、その材料がすでにどこかにあることです。1つの言語でプロダクトを出しているチームなら、ブランドガイドラインのページも、スタイルガイドも、サポート担当者に「絶対に翻訳しないで」と伝えている用語集も持っています。エンジンを手作業で設定するには、それらの文書を読み、判断を1つずつ、ロケールごとにレコードへ落とし込まなければなりません。時間がかかるうえに、いちばん時間を取られる部分ほど面白くない。すでに書かれている知識を、別の形式へ写し替えるだけだからです。
プロビジョニングは、その手間をなくします。プラットフォームに渡すのは文書そのものです。クロール対象のURLでも、生テキストでもかまいません。あとはAIエージェントが読み取りと転記を行い、実際のエンジン上にブランドボイス、用語集、指示のレコードを作成し、見つかったものから順に反映していきます。その後は、自分で作成したものと同じように、ダッシュボードでレビューして調整できます。出発点は空のエンジンではなく、設定済みのエンジンです。
プロビジョニングはエンジンを設定するもので、翻訳そのものは行いません。
このAPIが行うのは、エンジンの作成と設定です。作成後のエンジンで翻訳するには、多数のロケールをまとめて扱う async Localization API、または単一のロケールペア向けの synchronous Localize endpoint を使います。プロビジョニングは、それらの呼び出しに最初の翻訳からブランドボイスと用語集を乗せるためのセットアップ手順です。
仕組み#
ステップは3つあります。しかも、あなたのリクエストの中で行われるのは最初の1つだけ。残り2つはプラットフォーム側で非同期に進むため、呼び出しはすぐ返り、処理が終わる前からエンジンを使い始められます。
ソースを送信する
新しいエンジン名と、ソースの配列（クロールするURL、解析する生テキスト、またはその両方）を /jobs/provisioning にPOSTします。APIはすぐにエンジンを作成し、エンジンID（eng_）とジョブID（pjb_）を含む 202 を返します。アプリケーションはそのまま先へ進めて構いません。レスポンスは抽出の完了を待ちません。リクエストとレスポンスの完全な形式は プロビジョニングジョブを作成する を、どんなソースを送るべきかは ソースの種類 を参照してください。
AIエージェントがクロールして抽出する
リンクソースは並列にクロールされてテキスト化され、生コンテンツはそのまま読み取られます。その後、AIエージェントが全体を解析し、ブランドボイス、用語集項目、指示という3種類の設定を抽出して、見つかったものから順にエンジンへ反映します。あるソースのクロールに失敗しても、あるいは単一の項目を作成できなくても、残りの処理は止まりません。AIが抽出する内容 では、この3つの構成要素と、それぞれがロケールにどう対応するかを説明しています。
エンジンの準備が整う
抽出が完了すると、エンジンは完全に設定され、Localization API 経由ですぐに翻訳に使える状態になります。プラットフォームは、何が作成されたかの要約とともに、完了を webhook URL に通知します。実行中の進捗を表示したい場合は、job's WebSocket でリアルタイムに受け取ることもできます。
エンジンIDはすぐに使えます。
202 に含まれる eng_ ID は、受け取った瞬間から実在するエンジンです。すぐに保存、参照、翻訳に利用できます。設定はジョブの進行に合わせて反映されるため、早い段階で行った翻訳では、ジョブ完了後の翻訳より抽出済みレコードが少ないことがあります。エンジンを使い始めるのに、プロビジョニング完了を待つ必要はありません。
認証
REST でも WebSocket でも、すべてのリクエストは X-API-Key ヘッダーで認証します。キーは組織スコープで、組織内のすべてのエンジンにアクセスできます。詳しくは Authentication を、キーの作成方法は API Keys を参照してください。
返されるもの#
慎重な読者なら、すでに2つの問いを思い浮かべているはずです。これを安心して頼れるのかを決めるのは、ソースに問題があったらどうなるのか、そして修正不能なブラックボックスではないのか、という点です。
答えはどちらも明確です。プロビジョニングが返すのは独自形式の不透明な塊ではありません。実際のエンジン上に、通常のブランドボイス、用語集、指示のレコードを作成します。しかもそれらは、手作業で作るのとまったく同じオブジェクトで、あとからダッシュボードで編集できます。ジョブが完了すると、作成されたすべてのレコードと発生したすべての失敗を列挙した要約も返ってくるため、設定を推測で済ませず、きちんと確認できます。AIが抽出する内容 では、その要約の見方と、失敗した項目が errors リストに切り分けられ、エンジン全体の設定はそのまま進む仕組みを説明しています。
ソースは必須ではありません。sources なしで名前だけを送れば、デフォルト設定のクリーンなエンジンが作成され、自分で設定できます。プロビジョニングジョブを作成する では、そのパスも 202 レスポンスの形式とあわせて説明しています。プロビジョニングは手動セットアップを省くための仕組みであって、エンジンを持つための前提条件ではありません。
汎用的なページからは、汎用的な設定しか得られません。
設定の質は、送る内容の質に左右されます。ブランドガイドラインや用語リストなら、エージェントが具体的に抽出できる材料になりますが、マーケティング用のホームページから得られるものはほとんどありません。何を指定すべきかは ソースの種類 を参照してください。
これがプロビジョニングのトレードオフです。1回のリクエストと少しの待ち時間で、すでに書き留めてある知識をわざわざ転記する手間を省けます。すでにあるものを、そのまま渡すだけ。 そうして、空のエンジンではなく設定済みのエンジンから始められます。以下のページでは、その中身を順に見ていきます。
