過去記事が数百本あると、用語注釈を後から入れる話はたいてい途中で止まります。理由はほぼ一つ。全記事を機械で書き換えるのが怖い、これです。専門メディアほど本文の言い回しが命なので、一括処理でうっかり段落構造や引用が崩れたら取り返しがつきません。この記事は、その「まとめて入れたい」と「本文は守りたい」をどう両立させるか、そして数百本を慌てず回すための手順を書きます。
「注釈を入れる＝本文を書き換える」と思うから対立して見える
多くの人が思い浮かべる一括処理は、全記事の post_content を開いて用語のところに <span> などのマークを差し込み、上書き保存する、というものでしょう。これだと本文そのものが書き換わります。数百本を一度に触れば、意図しない箇所への一致や、ショートコード・独自ブロックとの相性で表示が崩れるリスクが残る。だから「一括はやりたいが本文はいじりたくない」という、相反する願いに見えてしまう。
ただ、この対立が成立するのは「注釈を入れる＝本文を書き換える」を前提にしたときだけです。表示のたびに注釈を組み立てる方式なら、本文を触らずに注釈を出せます。
見た目は保存せず、表示のときに組み立てる
用語注釈マネージャーでは、ツールチップの吹き出しや注釈ボックス、脚注の一覧といった見た目を投稿本文に保存しません。ページを表示する瞬間に、サイト共通の用語辞書（cam_term）と本文を照合し、その場で注釈の見た目を生成します。この「表示時に組み立てる」動作は、どの入れ方でも共通です。
用語の検出はAIではなく純粋なロジックで動きます。辞書に登録した用語名と別名（表記ゆれ）を本文と突き合わせ、DOMのテキストノードだけをたどり、最長一致を優先して拾う。読み方（ふりがな）は検索や並べ替えのための情報で、検出には使いません。何を注釈するかが辞書という一箇所で決まるので、全記事にまたがる管理を一本化できます。
全記事へ反映しても本文に手を触れない経路がある
ここが本題です。全記事へまとめて注釈を反映させる経路（全記事スキャン）では、承認した用語をメタ情報（_cam_active_terms）に記録するだけで、post_content には手を触れません。本文はバイト単位でそのまま。注釈の対象だという印だけを、記事のメタに持たせます。表示時にそのメタと辞書を見て注釈を出すので、本文を書き換えずに全記事へ反映できる。これが、一括と非破壊が両立する理由です。
ただし、線はきちんと引いておきます。個別記事のエディタで候補を「採用」したり、手で注釈を付けたりする入れ方は、本文に <span> のマークを挿入して保存します。こちらは本文に印が残る。つまり非破壊なのは「全記事スキャンの承認」であって、「どんな付け方でも本文を一切変えない」ではありません。全記事を安全にてこ入れしたいなら、本文へマークを書き込まない全記事スキャンを主に使う、という選び方になります。
ドライラン→確認→承認、そして取消は一度きり
非破壊だとしても、いきなり数百本へは流しません。全記事スキャンは、対象を投稿タイプ・ステータス・カテゴリー・著者・期間で絞ってから動かします。
まずドライランで、反映せずに候補だけを出す。候補は、用語・検出された文字・前後の文脈・表示形式・信頼度・状態が並ぶテーブルで確認できます。ここで絞り込み、納得したものだけを承認する。承認して初めてメタに記録されます。処理は途中で停止・再開でき、結果はCSVに書き出せます。
やり直しには注意が要ります。承認した反映を取り消せるのは、直前の1回だけです。何度でも巻き戻せるわけではないので、ドライランと候補確認を丁寧にやる前提の設計だと考えてください。ここを飛ばさないことが、数百本規模でも落ち着いて進めるコツになります。
過剰な一致を防ぐ歯止めと、触らない場所
一括で拾うときに困るのが、過剰な一致です。全記事スキャンには一致モード（ゆるい・標準・厳密）があり、日本語の助詞（を・が・は・に…）や英数字の境界を見て、変なところで語が切れないようにします。同じ用語でも既定では各記事の初回だけに注釈を付ける。短い語（日本語1〜2字・英数字2〜3字）はバッチの既定で対象外です。全記事へ雑に振らないための歯止めが、最初から入っています。
触ってほしくない場所も守ります。リンクの中・見出しの中・ボタンの中・コードの中は既定で除外（切り替え可）。CSSセレクタでの除外やブロック単位の除外もできます。既知の制約として、ショートコードが出力するテキストの中の用語は捕捉できません。この線引きを分かった上で使えば、本文の重要な部分に手を入れずに注釈だけを足せます。
少しずつ広げ、必要なら個別に寄せる
現実的な進め方はこうです。まず一部のカテゴリーや期間だけを全記事スキャンにかけ、ドライランで候補を見て、問題なければ承認する。そこで表示や検出の癖をつかんでから、対象を広げていく。全記事スキャンで土台を作り、どうしても本文にマークを固定したい記事だけ個別記事の採用に切り替える、という併用が扱いやすいはずです。
数百本の過去記事でも、辞書という一箇所を整えれば、注釈の中身は後からいくらでも直せます。本文を守りながら用語解説を全体へ広げる設計として、用語注釈マネージャーの全記事スキャンを土台に据える。これが、いちばん安全なてこ入れの入口になります。
より詳しい仕様は 用語注釈マネージャーの紹介ページ を参照してください。
