WordPress用語集のバックアップと移行：辞書をJSONで持ち出す

用語辞書を組み立てる場所と、その辞書が使われる場所は、同じサイトとは限りません。テスト環境で用語を並べて確認が済んでから本番へ入れる。構築したサイトをクライアントへ引き渡す。同じ業界向けの2サイト目で、前に作った辞書をもう一度使う。どれも動かしたいのは辞書だけで、記事本文には指一本触れたくない場面です。

本文の注釈も用語集ページも、実体はサイト共通の用語辞書1つです。用語注釈マネージャーでは、その辞書とカテゴリーをJSON設定やデータを受け渡すためのテキスト形式。メモ帳でも開けるが、Excelで表として開くものではなく、主にツール同士のやり取りやバックアップに使う。ファイル1つに書き出し、別のサイトへ読み込めます。窓口は管理メニューの「コンテンツ注釈 > インポート / エクスポート」。ただし辞書と一緒には動かないものがいくつかあって、そこを知らずに移すと、本番側で「用語は全部入っているのに注釈が1つも出ない」という状態から始めることになります。

テスト環境で組んだ辞書を、本番へ流し込む

いちばん多いのはこの向きでしょう。手順そのものは短い。

書き出しは1ボタンで全件です。範囲の指定はありません。下書きのまま置いてある用語も、無効にしてある用語も、まとめて1ファイルに入る。ここに絞り込みを付けなかったのは、控えのつもりのファイルが部分的だと、いざ戻すときに何が欠けているのか分からなくなるからです。選べるようにするかは何度か考えて、そのたびに見送っています。ファイル名には書き出した日時が入ります。

読み込みのほうは二段階に割ってあります。ファイルを選んで最初に出るのはプレビューで、この時点ではデータベースに何も書かれていない。画面の見出しにも「まだ保存していません」と入っています。一覧には用語ごとに新規・更新・スキップ・衝突・対象外のどれかが並び、その上に件数の要約が出る。ここで内容を見てから、取り込む行を選んで本適用へ進みます。

カテゴリーも一緒に運ばれます。書き出されるのはスラッグURLの末尾に使う、投稿やカテゴリーごとの英数字の名前。このサイトなら plugear.net/wordpress-japan-map/ の「wordpress-japan-map」の部分。と親のスラッグで、内部のIDは持ち出しません。だからIDの振られ方がまるで違う別サイトでも、階層はそのまま再現される。移し先に無いカテゴリーは取り込みのときに作られます。

同名の用語がぶつかると、どう扱われるか

移し先の辞書が空なら悩みません。問題になるのは、すでに用語が入っている本番へ後から流すときです。取り込み画面の「同名の用語があるとき」で、扱いを3つから選びます。

モード	既存の用語をどうするか
スキップ	手を触れない。同名があれば取り込み側を捨てる
マージ（既定）	空欄だけを補い、別名とカテゴリーは両方を足し合わせる
上書き＋追加	既存を取り込み側の内容で丸ごと置き換え、無い用語は新規追加

マージの線引きは細かく決めてあります。読み方・短い説明・詳細説明・詳細ページURLは、既存が空のときだけ埋まる。別名とカテゴリーは既存と取り込み側の和集合になり、重複は落ちます。そして表示形式・有効/無効・用語集への掲載・検出設定・下書きかどうかは、既存の値がそのまま残る。つまり本番で調整した設定は、テスト環境から持ってきたファイルでは動きません。

既定をマージに寄せてあるのは、取り込み漏れより上書き事故のほうが痛いからです。スキップなら足りない分を後から足せる。上書きで消えた説明文は、控えを取っていなければ戻せません。

同名の用語が移し先に2件以上あるときは、どのモードを選んでも自動では処理せず、「衝突」として対象外に置きます。手で片付けてくださいという合図。粒度の違う重複登録が辞書に眠っていると、この行で表に出ます。

もう一つ、往復しても壊れない仕掛けが入っています。取り込む用語の公開状態は publish と draft しか受け付けず、それ以外や欠落は draft に丸める。マージのときは公開状態に触らない。テスト環境と本番のあいだで何度かファイルを行き来させても、下書きのまま寝かせていた用語が勝手に公開されることはありません。

JSONに入るもの、入らないもの

ここが移設のときにいちばん効いてきます。

一緒に運ばれる	運ばれない
用語名・読み方・短い説明・詳細説明	記事の本文
別名（表記ゆれ）・詳細ページURL	どの記事でどの用語を有効にしたかの記録
表示形式・有効/無効・用語集への掲載	全記事スキャンの候補テーブル
カテゴリー（階層のまま）	AIのキー
用語ごとの検出設定	プラグインの設定（色・除外ルール・構造化データページの内容を、検索エンジンなどの機械が読み取りやすい決まった形式で書いた情報。schema.orgの語彙を使い、JSON-LDで埋め込むのが一般的。詳しく見る・用語集ページの指定）

右側の2行目が、冒頭で書いた「用語は全部入っているのに注釈が出ない」の正体です。全記事スキャンで承認した内容は、本文ではなく投稿のメタ情報に記録されます。本文を書き換えずに全記事へ注釈を行き渡らせられるのはこの作りのおかげですが（本文が書き換わらない仕組み）、記録の置き場所が投稿側である以上、辞書の書き出しには乗ってきません。移し先では辞書を入れたあと、もう一度ドライランから回すことになります。下ごしらえの手順は全記事一括注釈の下準備のほうに書きました。

裏を返すと、記事ごとサイトを移す場合はこの作業が要りません。サーバーを引っ越して投稿もメタ情報も丸ごと持っていくなら、有効化の記録も一緒に動きます。JSONの出番は、投稿とは切り離して辞書だけを動かしたいときです。

左側の最終行も見落とされがちなところ。一致モードや助詞の扱いといった境界判定のトグルは、用語1件の情報として書き出されます。テスト環境で1語ずつ詰めた検出条件は運べる、ということ。逆に、除外ルールやCSSセレクタ除外のようなサイト全体の設定は入っていないので、移し先で入れ直しになります。各欄が何を担当しているかは用語辞書を1件ずつ育てるに整理してあります。

引き渡すときは、ライセンスの籍も動かす

制作会社が構築して納品する形だと、辞書より先に決めるものがあります。ライセンスです。

ライセンスは1サイトでアクティベートする方式で、ライセンス画面に「有効化」と「無効化」のボタンが並びます。状態は未認証・有効・期限切れ・停止中・失効で表示される。無効化すれば、そのキーを別のサイトで有効化し直せます。

制作用のキーを入れたまま引き渡すと、更新の通知も自動アップデートも制作側に紐づいたまま残ります。引き渡しの段で無効化し、クライアントのキーで有効化し直す。順番としてはそれだけですが、抜けると先方のサイトにだけ更新が届かない状態ができます。

もう一点。「設定」のいちばん下に、アンインストール時にデータをすべて削除するというチェックがあります。既定はオフ。オンのまま引き渡すと、あとで誰かがプラグインを削除したときに用語データもライセンス情報も一緒に消えます。動作確認のために触った覚えがあるなら、渡す前にオフへ戻しておくのが無難です。

そのうえで辞書のJSONを1本添えておけば、先方の手元にも復元の材料が残ります。渡す前に自分でその1本を空の環境へ読み込んで、プレビューの一覧までは試しておく。カテゴリーの階層が思ったとおりに再現されるかは、そこで初めて目に見えます。

同じ辞書を2つのサイトで使うのは、共有ではなく複製

3つ目の場面です。同じ分野のサイトを複数持っていて、用語の説明を揃えたい。

先に線を引いておくと、1つの辞書を複数のサイトから参照する形にはなりません。マルチサイト1つのWordPressで複数のサイトをまとめて運営する機能。有効にするとプラグインの動き方が変わり、対応していないプラグインもある。にも対応していないので、各サイトがそれぞれ自分の辞書を持ち、そこへ同じ内容を配る形になります。共有ではなく複製。

この形で運用するなら、原本を1つ決めてしまうのが結局いちばん軽い。用語を足すのも直すのも原本側だけで行い、書き出したファイルを他のサイトへマージで流します。マージなら、受け側だけで足したローカルの用語は残り、受け側で選んだ表示形式や検出設定も動きません。上書き＋追加を選ぶと、そこまで原本の値に戻ります。

原本側で消した用語を配布先からも消したい、という要求もあるでしょう。取り込み画面には「ファイルに無いローカル用語を削除する」というチェックがあり、これを使えば移し先をファイルの内容に強制的に揃えられます。ただしこの削除はゴミ箱を経由しません。取り消しもできない。画面上でもこの項目だけ警告色の枠に入れて、取り消せない削除だと明記してあります。プレビューには削除される用語も並ぶので、そこに何が入っているかを数えてから本適用へ進んでください。

なお、上限は読み込む側にあります。1ファイルにつき用語5000件・8MiBを超えると、プレビューまで進まずに弾かれる。日本語の辞書で当たる天井ではないはずですが、決まってはいます。

大きく触る前に、控えを1本取っておく

移行の話から少し外れますが、書き出しがいちばん効くのは移す瞬間ではなく、辞書を大きく動かす前かもしれません。

用語辞書には、チェックを入れた用語へまとめて効く一括操作があります。まとめて効くということは、選択範囲を間違えたときも同じ勢いで効くということ。一覧の広い範囲を選んだ状態で操作を押す前に、「JSON をダウンロード」を一度挟むと、判断の重さが変わります。ファイル名に日時が入るので、控えを何本か並べても新旧で迷いません。

ひとつ正直に書いておくと、この控えで戻せるのは辞書だけです。全記事スキャンで承認した反映を巻き戻せるのは直前の1回きりで、そこは辞書のJSONとは別のレイヤーにあります。承認の往復はドライランの中で済ませる、という原則のほうは変わりません。

辞書は積み上げるほど価値が出る資産で、その価値は持ち出せて初めて安心して積める性質のものだと思っています。書き出し・読み込みの画面がどこにあるかは、用語注釈マネージャーの製品ページから辿れます。