ソースの送信は完了し、ジョブは実行中です。エンジンIDは 202 で返され、その設定が埋まり始めています。このページで答えるのは、結果を信頼できるかを左右する問いです。いったい何が、具体的に埋まっているのか？
「AIが自分のエンジンを設定した」という言い方に、エンジニアが身構えるのはもっともです。その警戒は正しい反応でもあります。中身を確認できないブラックボックスなのかもしれない。把握しきれないまま、ロケールごとにレコードが散在するのかもしれない。情報の薄いソースを読んだ結果、何も見つからず、ほとんど何も作られていないのかもしれない。だからこのページでは、その3点をすべて具体的に説明します。エージェントが作る設定は3種類あり、それぞれは予測できるルールに従ってロケールに対応づけられ、ジョブは作成した全レコードを名前付きで示すサマリーを返します。出力されるのは、読んで編集できる通常のレコードであって、黙って受け入れるしかない判定結果ではありません。
非同期プロビジョニングが初めてなら、まずは考え方の全体像がわかる Async Provisioning API overview と、送信する価値のあるソースが何かを説明する Source types から読むのがおすすめです。このページで扱うのは、その先で何が出てくるのかです。
このページの内容
3つの構成要素#
エージェントは、クロールしたページでも生のコンテンツでも区別なく読み取り、3種類のエンジン設定を作成します。これはプロビジョニング専用の新しい形式ではありません。いずれも エンジン 上で本来手動作成するのとまったく同じ基本要素です。だからこそ、エージェントが作成したものはすべて、あとからダッシュボードで編集できます。自分で作ったものを編集するのと同じ感覚です。
| 構成要素 | 抽出対象 | 例 |
|---|---|---|
| ブランドボイス | トーン、文体、フォーマルさのレベル、文体上のルール | 「フォーマルなドイツ語（Sie-form）を使う。文は簡潔で直接的に保つ。」 |
| 用語集項目 | 製品名、技術用語、ブランド固有の訳語、非翻訳語 | 「Acme」→ 非翻訳、「workspace」→ 「Arbeitsbereich」（de） |
| 指示 | 書式ルール、文化的な慣習、ドメイン固有のガイドライン | 「ドイツ語訳では日付を必ず DD.MM.YYYY 形式で表記する。」 |
この3つがあるからこそ、翻訳はただの無難な言い換えではなく、あなたの製品らしい表現になります。選んだフォーマルさ、決して翻訳しない名称、常に使う日付形式。エージェントの役割は、そうした判断がソースのどこに書かれていても見つけ出し、レコードとして残すことです。
ここでひとつ、期待値の上限を決める大事な点をはっきりさせておきます。エージェントが抽出するのは、明示されていることです。ルールがはっきり書かれていればレコードになります。反対に、よいトーンをなんとなく示しているだけで、ルールとして言語化されていないソースから得られるものは多くありません。これはエンジンの限界ではなく、ソース側の性質です。Source types では、ルールが明確に書かれたソースをどう選ぶかを説明しています。
各要素がロケールにどう対応づけられるか#
ローカライゼーションエンジンの設定は対象ロケールごとに管理されるため、レコードにはルールの内容だけでなく、そのルールがどこに適用されるかも含まれます。エージェントは予測できるルールに従って各レコードにロケールを割り当てます。出力を読む前に理解しておきたいのが、* ワイルドカードです。
- ブランドボイスと指示は、すべての言語にまたがって適用される場合、
*を使います。 たとえば「文は簡潔で直接的に保つ」というトーンルールは、ドイツ語だけの話ではありません。製品があらゆる言語でどう書くかを示すルールです。エージェントはこれを対象ロケール*に割り当て、エンジンが翻訳するすべてのロケールに適用します。本当に言語固有のルール（「ドイツ語では Sie-form を使う」など）の場合は、そのロケールに割り当てられます。 - 用語集項目はロケールペアごとに作成されます。翻訳は常に、ある言語から特定の別言語への対応だからです。たとえば「workspace」→「Arbeitsbereich」はドイツ語に関する事実であり、ドイツ語にしか当てはまりません。
- 非翻訳語は例外で、
*を使います。 たとえば決して翻訳しないブランド名「Acme」は、どの言語でも非翻訳です。したがってロケールペアごとに入れ直すのではなく、*に対して一度だけ保存されます。
つまり、ジョブが作成したレコードに * が入っていても、それはプレースホルダーでも未設定でもありません。「これはどこでも適用される」という意味です。グローバルなトーンルール、グローバルな指示、あるいはどの言語でも翻訳しない用語を表しています。逆に特定のロケールコードが入っていれば、そのルールはその言語にだけ適用されるということです。
ワイルドカードは上書きすべきデフォルトではなく、意図を表す機能です
* を見て、「エージェントがどのロケールに属するかを判断しなかったのでは」と疑いたくなるかもしれません。実際は逆です。すべての言語で正しいブランドボイスや非翻訳語は、グローバルであるべきです。1つのロケールに固定してしまうと、ほかのロケールには静かに適用されなくなります。ワイルドカードは、「これは言語に関係なく成り立つ」ということを設定で表す方法です。トーンルールやブランド名は、まさにそういう性質のものです。
出力サマリー#
ジョブが完了すると、エージェントが作成したものをすべて列挙するサマリーが返されます。いわば受領書です。すべてのレコードが件数付きで識別され、あわせて失敗したものの一覧も含まれます。
{
"brandVoices": {
"count": 3,
"ids": ["bv_A1b2C3d4", "bv_B2c3D4e5", "bv_C3d4E5f6"]
},
"glossaryItems": {
"count": 12,
"ids": ["gi_A1b2C3d4", "gi_B2c3D4e5", "..."]
},
"instructions": {
"count": 5,
"ids": ["ins_A1b2C3d4", "ins_B2c3D4e5", "..."]
},
"errors": []
}各構成要素では、作成されたレコードの count と ids が報告されます。ブランドボイスは bv_、用語集項目は gi_、指示は ins_ です。これらは曖昧な受領確認ではなく、エンジン上に存在する実際のレコードIDです。この一覧にある任意の gi_ を使えば、ダッシュボードで開いて、エージェントが抽出した内容をそのまま読み、必要なら変更できます。サマリーによって、「AIが何かをした」から「AIがやった20個の具体的なことがここにある」へと認識を切り替えられます。そこが、ブラックボックスと読んで編集できる通常のレコードの決定的な違いです。
このサマリーは、ジョブ作成時に設定したチャネルで届きます。完了時にコールバックURLへ送られる webhook ペイロードの summary フィールドです。WebSocket でジョブを監視している場合、それは稼働状況を伝えるフィードであり、クロールや設定の進行は流れますが、このサマリーオブジェクト自体は流れません。サマリーは完了 webhook に含まれ、WebSocket はそれを読みにいくタイミングを知らせます。
1件失敗しても、ジョブ全体は失敗しません
1つのレコードが作成できなくても、それで残りすべてが無駄になることはありません。失敗は errors 配列に記録され、成功したレコードはそのままエンジンに適用され、ジョブ自体も完了します。返ってくるのは、部分的に設定済みのエンジンと、見直すべき箇所を正確に示した一覧です。空のエンジンとスタックトレースではありません。実行全体が失敗するのは、そもそも処理対象が何も得られなかったときです。たとえば、すべてのソースでクロールに失敗した場合などです。その失敗ケースと provisioning.failed ペイロードについては、Webhook delivery で説明しています。
情報の少ないサマリーの読み方#
サマリーは、何が作成されたかだけでなく、件数を通じてその実行にどれだけ意味があったかも教えてくれます。ある構成要素の count が 0 でも、それ自体はエラーではありません。サマリーの形式は正しく、エンジンも作成されています。ただし、それは重要なシグナルです。ブランドボイスが3件、用語集項目が12件なら、設定されたエンジンと言えます。すべてがゼロで errors 配列も空なら、返ってきたエンジンはほぼ空に近く、エージェントが抽出できるルールをほとんど見つけられなかったことを示しています。
そうなったとき、原因はほぼ例外なく上流にあります。つまり、エージェントが拾い上げられる具体的なルールがソースにほとんど書かれていなかったということです。それに気づく場所がサマリーであり、見直す場所が Source types です。最初の実行で持っておくべき率直な期待値はシンプルです。受領書に反映されるのは、ソースが実際に明言していたことだけ。サマリーが充実していればソースも充実しており、サマリーが薄ければ、見つけられるものも少なかったということです。
だからこそ、サマリーはエンジンそのものと同じくらい重要です。思い込みではなく、設定内容を検証できるからです。件数を確認し、いくつかのレコードをIDで開き、エージェントが期待どおりの内容を拾えているかを確かめてください。読んで編集できる通常のレコードと、何を確認すべきかを正確に示す受領書。それが重要です。
