WordPressで用語のツールチップが表示されない — 吹き出しより先に下線を確かめる

用語を辞書に登録して、全記事スキャンまで回した。それなのに記事を開くと、注釈らしきものがどこにも見当たらない。ここで設定画面を上から順に総ざらいすると、だいたい時間だけが溶けていきます。

用語注釈マネージャーのツールチップは二段構えです。まず本文の用語そのものに下線やアイコンの印が付き、その印にホバー（スマホならタップ）すると吹き出しが開く。つまり「表示されない」という症状は二種類あります。印すら出ていないのか、印は出るのに吹き出しが開かないのか。原因を並べる前に、まずここを分けてください。

下線が出ているかで、見に行く場所が半分になる

対象の記事をフロントで開き、注釈を付けたい語を目で探します。確認するのは吹き出しではなく、その語に下線か小さなアイコンが付いているかどうか。

この二分には根拠があります。注釈が1件でも描画されたページにだけフロントのJavaScriptが読み込まれる設計なので、印が出ていないページでは、吹き出しを開く仕掛けがそもそも走っていない。印が無い状態で表示まわりの設定を疑っても、当たりません。

印がどこにも無いなら、辞書の3行を先に疑う

用語が無効になっている。 用語辞書の各エントリは有効・無効を持っていて、無効にした用語は注釈に使われません。一括操作の「無効化」をかけた分がそのまま残っていることもある。まず用語一覧で、その語の状態を見ます。

表記を読み方の欄に入れている。 ここが一番の落とし穴。読み方（ふりがな）は用語集の50音並べ替えと管理画面の検索のための欄で、本文の検出には使われません。用語名を「NISA」で登録して読み方に「にーさ」と書いても、本文の「ニーサ」は拾われない。カタカナ表記も略称も英字も、拾わせたい表記はすべて別名に入れます。どの欄が何を担当しているかは用語辞書を1件ずつ育てるに整理してあります。

候補を承認していない。 全記事スキャンは、ドライランで候補テーブルを出すところまでが最初の段です。テーブルに用語が並んでいても、それは見つけただけの状態。承認して初めて、その投稿で注釈が有効になります。スキャンを流したのに何も変わらないなら、候補の状態列を見てください。

辞書が正しくても、その場所なら初めから対象外

登録内容に問題がなくても、用語が置かれている場所によっては検出そのものが走りません。

リンクの中・ボタンの中・コードの中。 この3か所は設定に関係なく、常に検出の対象外です。見出しの中も既定では外れている。アンカーテキストの中にしか出てこない用語、見出しにしか書かれていない用語は、設定画面をどう触っても拾われません。リンクの中を外してあるのは、リンクをたどる操作と吹き出しを開く操作が同じ文字の上で重なるからです。特にスマホでは、どちらを意図したタップなのか読者にも判別できなくなる。

2文字以下の用語は最小文字数で落ちる。 日本語でも英字でも、2文字以下の用語は既定の検出から外れます。SSO や API のような3文字の略語は対象に入るので、こぼれるのは「与信」「工数」といった2文字の語のほう。全記事スキャンだけでなく記事編集画面の候補パネルにも同じ下限がかかるので、そちらへ回しても出てきません。この長さの語にどうしても注釈を付けるなら、エディタのツールバーにある「注釈」から手で付ける経路になります（本文にマークが残る点を承知のうえで）。

ショートコードが出力したテキストの中にある。 これは既知の制約です。ショートコードは本文フィルタより前に展開されるため、そこから出てきたテキストの中の用語は捕捉できません。設定では解決しないので、用語集ページなど別の見せ方へ回す判断になります。

除外や短語のしきい値を承認前に整えておく手順は全記事一括注釈の下準備のほうに書きました。あちらは付きすぎを抑える話ですが、触る画面は同じです。

同じ記事の上のほうに、もう付いていないか

ページ全体に一つも印が無いのか、いま見ている段落にだけ無いのか。ここも分けておく価値があります。

既定では、同じ用語は各記事の初出の1回にだけ注釈が付きます。記事の中ほどで用語が裸のまま出てくるのは、たいていそのせい。ページを上へさかのぼると、最初の1回にはきちんと印が付いているはずです。段落単位で見ていると、この既定は誤解しやすい。

初回のみは用語ごとの検出条件で切り替えられます。ただし専門用語の多い記事で全出現に付けると、本文が下線だらけになって読みづらくなる。ここは既定のままが無難です。

印は出ている。吹き出しだけが出てこない

印が出ているなら、検出は通過しています。残っているのは見せ方の問題。

表示形式がツールチップ以外になっている。 表示形式は用語ごとに既定を持てるので、注釈（注釈ボックス）や脚注を選んでいれば、説明は吹き出し以外の場所に出ます。注釈なら用語を含む段落の下に枠、脚注なら本文に連番が入り、記事末尾に一覧。吹き出しが開かないのではなく、開く形式ではなかった、という話です。3つの形式の性格の違いはWordPressで専門用語に注釈・ツールチップを付ける完全ガイドにまとめてあります。

短い説明の欄が空になっている。 本文の注釈として表示される説明文は、ツールチップでも注釈ボックスでも脚注でも「短い説明」の欄から取られます。詳細説明のほうだけ書いて短い説明を空にしていると、吹き出しに出す中身がない。エディタで注釈のポップオーバーを開いてプレビューを見ると、この欄が空の用語には「説明文が未設定です」と表示されます。詳細説明の欄を読むのは用語集ページと構造化データページの内容を、検索エンジンなどの機械が読み取りやすい決まった形式で書いた情報。schema.orgの語彙を使い、JSON-LDで埋め込むのが一般的。詳しく見るのほうです。

ホバーできない環境で見ている。 スマホやタブレットにホバーはなく、ツールチップはタップで開く前提です。PCで確認したはずが手元の端末では反応しない、あるいはその逆。どの端末で見たのかを記録しておくと、切り分けが速くなります。

語の切れ目の判定に手を伸ばすのは、いちばん最後

ここまでで直らないと、検出条件の一致モードに手が伸びます。ゆるい・標準・厳密の3つ。ただ、これを緩めるのは順番として最後に置いてください。

一致モードはサイト全体のダイヤルではなく、用語1件ごとに持つ設定です。1語のために触っても、隣の用語には何も起こりません。

この段で先に見る価値があるのは「後ろが助詞なら除外しない（を/が/は/に…）」のトグルです。既定はオフ。日本語の文章では用語のすぐ後ろに助詞が続くのが普通なので、ここが効く場面はあります。

当たる順番はこうなります。印の有無で二分する。印が無ければ辞書（無効・別名・承認）、次に用語が置かれた場所（除外・最小文字数・ショートコード）、そしてページ上部の初出。印があるなら表示形式と短い説明。検出条件を動かすのは、そのすべてを潰してから。

どの設定がどの画面にあるかは、用語注釈マネージャーの製品ページから辿れます。