Claude Codeに自作WordPressプラグインの英語化を任せた｜翻訳ファイルを同梱しても切り替わらない原因が load_plugin_textdomain 不在だった全記録（Plugin Check未完了まで書く）

① 公開中のプラグインに、日本語が305か所残っていた

「orgに通ったプラグインって、英語圏の人も使える仕様になってるよね？」

2026年9月14日の深夜0時すぎ。何気なく口にしたこの一言で、私の週末の予定が消えました。

私は普段、エンジニアとして開発に関わりながら、AI導入支援やAI活用のレクチャーも行っています。個人開発のWordPressプラグインを公式ディレクトリで5本配布していて、どれもreadmeは英語。説明文も英語。だから「英語圏の人が入れても普通に使える」と思い込んでいました。

答えは「5本中1本が未達」でした。

問い合わせフォームのプラグイン（当時2.0.2）は、翻訳関数の中に日本語の原文が305か所（ユニーク253）残っていた。しかもJavaScriptの中には翻訳関数すら通っていない日本語が admin.js に19行・frontend.js に16行。極めつけは、同梱した日本語の翻訳ファイル（.mo）を読み込む load_plugin_textdomain() と Domain Path ヘッダがそもそも存在しなかったこと。

つまり英語ロケールのサイトに入れても日本語が出る。そして日本語サイトに入れても「翻訳ファイルで日本語にしてる」わけではなく、単に原文が日本語だから日本語に見えていただけ。翻訳の仕組みは1ミリも動いていませんでした。

このnoteは、その状態から翻訳呼び出し313箇所を旧版と1対1で照合して差分0、英語ロケールでの日本語残存0件まで持っていった記録です。作業の実行はClaude Code（私のAI秘書）に任せ、私は検収と判断だけをやりました。同じ週に別のプラグイン4本でも翻訳ファイルの同梱をやっていて、そこで踏んだ失敗もまとめて書きます。

Plugin Checkが未完了のまま終わっているところまで、正直に書きます。

② 「翻訳ファイル入れたから大丈夫」って思ってませんでした？

思ってました。私が。

• languages/ フォルダに xxx-ja.po と xxx-ja.mo を置いた

• readme.txt は英語で書いた

• プラグインヘッダに Text Domain は書いてある

• 手元の日本語サイトで動かしたら日本語で表示された

この4つが揃うと「多言語対応できてる」って気分になる。でもこの4つは全部翻訳が動いている証拠にはならないんですよ。

手元の日本語サイトで日本語が出るのは当たり前です。原文が日本語なんだから。翻訳ファイルが読まれていようがいまいが日本語が出る。だから「読まれていない」ことに気づけない。

逆に英語のサイトを1回でも立てて入れてみれば秒で分かる。私はそれをやっていなかった。公開してから数日、誰も指摘しなかった。英語圏の人が入れて日本語の管理画面を見て黙って消していった可能性はある。それは計測できていないので「分からない」としか書けません。

もしあなたが今、次のどれかなら、この記事は自分事です。

• .po/.mo を同梱したのに、WordPressの言語設定を変えても表示が変わらない

• 英語のサイトに入れたら日本語が混ざって出た（またはその逆）

• 管理画面は切り替わるのに、JavaScriptで出しているメッセージだけ日本語のまま

• 翻訳したら管理画面のCSSやJSが読み込まれなくなった

• 更新版を出したのに、自分のサイトの管理画面に更新の通知が出ない

上の5つ、全部私が2026年9月の1週間で踏んだやつです。←全部です

③ 問題の正体｜「翻訳対象」と「読込経路」が分断されている

原因を1つずつ潰す前に、構造を見せます。翻訳が効かない自作プラグインは、だいたい次の5層のどこかで切れています。

層1: 原文が日本語のまま

WordPressの翻訳（gettext）は「英語の原文 → ロケールごとの訳」という一方向の仕組みです。__( '送信', 'my-plugin' ) と書いてしまうと、原文が「送信」になる。英語ロケールのサイトで英語を出すには「送信 → Send」というen_US向けの翻訳ファイルが要る。そんなものは普通作らないので、英語サイトでも「送信」が出る。

私のフォームプラグインはこれが305か所。翻訳関数は通っているのに原文が日本語だから、翻訳の仕組みとしては「日本語→日本語」しかできない状態でした。

層2: 同梱した .mo が読まれていない

ここが今回の本丸です。

.mo を languages/ に置くだけではWordPressは読みません。プラグインが自分で load_plugin_textdomain() を呼ぶか、あるいは公式ディレクトリ配布版で translate.wordpress.org の言語パックに乗るか。どちらかが必要です。

公式ドキュメントにはこうあります。WordPress 4.6以降、translate.wordpress.org の翻訳が優先されるため、そこで翻訳されているプラグインは load_plugin_textdomain() を必ずしも必要としない。 https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/

これを逆から読むと、translate.wordpress.org に翻訳が無い（自分で .mo を同梱している）プラグインは、自分で読み込まないと何も起きないということです。

私のフォームプラグイン 2.0.2 には load_plugin_textdomain() が無かった。ついでに Domain Path ヘッダも無かった。同梱した .mo は「置いてあるだけ」でした。

さらに厄介なのが、同じ週に直した内部リンクのプラグインで1.0.2 で load_plugin_textdomain が削除されていたこと。過去のバージョンには入っていた。リファクタのどこかで消えていた。「前は動いてたから」は当てにならないと身をもって学びました。

層3: JavaScript の中のハードコード日本語

PHP側を全部英語にしても、JSファイルに直書きした日本語は翻訳関数を通っていないので絶対に切り替わりません。

フォームプラグインで admin.js に19行・frontend.js に16行。内部リンクのプラグインでは link-map.js に7文言。PDFスライドのプラグインでは44文言のうちJSが33（PHP8・共通1・block.json 2）。JSの方が多いプラグインもあるんですよ。PHPだけ棚卸しすると半分以上を見逃す。

WordPress側の正攻法は2つ。wp_localize_script() で翻訳済み文字列をPHPからJSへ渡す方法と、wp_set_script_translations()（5.0以降）でJS側の wp.i18n に翻訳を紐づける方法です。 https://developer.wordpress.org/reference/functions/wp_localize_script/ https://developer.wordpress.org/reference/functions/wp_set_script_translations/

私はフォームプラグインで前者、PDFスライドで後者を使いました。どちらが正しいというより、既存コードの作りで選びました（理由は⑤で）。

層4: 「既定値」として保存される日本語

見落としがちなのがここ。設定画面の初期値に日本語が入っているケースです。

フォームプラグインには問い合わせを自動分類するキーワードの既定値が5本あって、これが日本語で直書きされていた。英語ロケールで入れた人は、設定画面を開いた瞬間に日本語のキーワードが並ぶ。しかも一度保存すると設定値としてDBに残るので、あとから翻訳を足しても保存済みの値の方が優先されて変わらない。

「表示の翻訳」と「データの初期値」は別物です。ここは _x()（文脈つき翻訳）でロケールごとに違う既定値を返すようにしました。

層5: 配布物と導入先の版がずれている

直したあとの話です。修正版を配布しても、自分のサイトに入っているのが古い版のままなら、確認は全部無意味。

私は修正版を公開した直後に自分のサイト2つを更新しようとして、公式の更新チェックAPIが未反映で管理画面に更新の行が出ないという状態に当たりました。さらに片方はマルチサイト。しかも確認に使おうとしたURLが実は存在しないページで、それでも ?ver=2.0.3 が取れてしまう罠まであった。

「直した」と「直ったものが動いている」の間には、ちゃんと溝があります。

5層をまとめると

| 層       | 症状                                     | 原因                                         |
|----------|------------------------------------------|----------------------------------------------|
| 1 原文   | 英語サイトでも日本語が出る               | 翻訳関数の原文が日本語                       |
| 2 読込   | .mo を置いても何も変わらない             | load_plugin_textdomain()／Domain Path が無い |
| 3 JS     | 画面は切り替わるのにメッセージだけ日本語 | JSに直書き                                   |
| 4 既定値 | 設定画面の初期値が日本語                 | 既定値が翻訳を通っていない・保存値が優先     |
| 5 版     | 直したはずなのに変わらない               | 導入先が旧版・更新通知が未反映               |

このnoteの有料部分は、この5層を順番に潰す手順と、各層で私が実際に測った数字と、踏んだ穴です。

④ 転機｜「readmeを英語化して」と頼んで、前提が間違っていた

順番に書きます。成功の前に失敗が3つあります。

失敗1: 存在しない問題を直しに行った（9月7日）

最初に私が出した指示は「公開中のプラグイン4本のreadmeを英語化して」でした。

結果は前提が誤り。4本ともreadmeは最初から英語だった。公開時の要件で英語化済みで、しかも公開版と開発版が同一。AI秘書は「readmeは既に英語です」と報告してきて、私は配車前に自分で確認していなかったことに気づきました。配車前のAPI確認が失敗していたのに、そのまま前提を確かめずに投げていた。

でもこの空振りが転機になった。AI秘書が「readmeは英語だが、代わりにこういう穴があります」と3つ持ってきたからです。

1. 内部リンクのプラグインはUIが日本語 103/103。英語圏の人が入れても日本語の管理画面が出る

2. AI引用診断のプラグインはスクリーンショット0枚・「Tested up to」が7.0（他3本は7.1）で一覧面で不利

3. PDFスライド・AI引用診断・WooCommerce連携の3本はUIは英語だが ja.po/.mo が無い。日本語ユーザーには英語画面

そして3番目には注釈がついていた。「WooCommerce連携は8月31日の記録に『ja.po/mo同梱』とあるが、作業フォルダには .pot しか無い。要確認」。

確認したら記録が間違っていました。同梱したつもりで .pot しか作っていなかった。自分の記録すら当てにならない。

失敗2: 「103か所残っている」という報告が、古いソースを見た誤報だった（9月14日）

9月7日にAI秘書は内部リンクのプラグインを 1.0.3 として英語UI化しました（翻訳関数103箇所・ユニーク78を英語原文へ）。

ところが9月14日の深夜、冒頭の「英語圏の人も使えるよね？」の問いにAI秘書が返してきた第一報は「フォームプラグインは未達。内部リンクも103か所残存」でした。

え、7日に直したよね？

調べると、AI秘書が見ていたのがローカルの作業フォルダに残っていた古い版のソースでした。公開中の 1.0.4 を公式ZIPで取り直して実測したら日本語は0件。つまり内部リンク側の作業は不要だった。

ここで手を動かしていたら、直っているものを二重に直して版だけ上がるところだった。「配布中の現物を取って測る」を最初にやらなかったのが原因です。層5の「配布物と導入先の版」を、直す側でも踏んだわけです。

失敗3: 1.0.2で load_plugin_textdomain が消えていた

内部リンクのプラグインを英語化する途中で、AI秘書が「調査で見落としていた3点」を追加で見つけて直しました。

1. link-map.js にハードコードの日本語7文言 → wp_localize_script 経由へ

2. enqueue_scripts() がメニュー名由来のhook suffix '内部リンク_page_…' を直書きしていた。メニュー名を翻訳するとこの文字列が一致しなくなってCSSとJSが読み込まれなくなる → add_menu_page() の戻り値を使う形へ

3. load_plugin_textdomain が 1.0.2 で削除されていた。同梱の .mo は無いと読めない → 復元

2番は翻訳とは無関係に見えて翻訳が引き金になるバグ。翻訳して初めて壊れる。日本語のまま使っていたら一生気づかなかったやつです。

3番は「前の版では入っていた」もの。差分を追わずに「翻訳ファイルを同梱すれば終わり」と思っていたら、ファイルは同梱されているのに何も起きないという状態を量産するところでした。

そして本丸のフォームプラグイン（9月14日 0時半〜1時）

内部リンクは作業不要と分かり、残るはフォームプラグイン1本。ここからは⑤の手順そのものなので、結果だけ。

• 翻訳関数内の日本語305か所（ユニーク253）→ 英語原文へ

• admin.js 19行・frontend.js 16行 → wp_localize_script の i18n へ

• 分類キーワードの既定値5本 → _x() 化

• Domain Path: /languages ＋ init フックでの load_plugin_textdomain() を追加

• .pot（278エントリ）＋ ja.po/.mo（272訳）を同梱

• 検証: php -l 全PHP 0エラー／node --check 全JS 0エラー／翻訳呼び出し313箇所を旧版2.0.2と1対1で照合し、.mo適用後の日本語が全件一致（差分0）／英語ロケールで翻訳関数内の日本語0件

• 2.0.3として公開。公式ZIP（95,367B）を展開して ._ ファイル0件・languages/ 3ファイル同梱を確認

• 自分のサイト2つへ適用し、管理画面の一覧とフロント3ページで英語混入0を実機確認

30分ちょっとでここまで行ったんですけど、正直に言うと私が手でやっていたら1日かかってたと思います。305か所を英語にして、しかも旧版の日本語表示と1対1で一致させるって、人力だと必ず数か所ズレる。

で、Plugin Check（公式の静的チェック）は未実行のままです。理由はWP-CLI未導入。これは⑥で書きます。

この記事が向いている人／向かない人

向いている人

• 自作のWordPressプラグインを配布していて、翻訳ファイルを同梱したのに切り替わらない人

• 日本語で書いたプラグインを英語圏にも出したい人

• 「翻訳ファイルを入れたはず」を、動いている証拠つきで確認したい人

• 英語化のような大量置換をAIに任せて、自分は検収に回りたい人

向かない人

• translate.wordpress.org の言語パックで運用していて、同梱の .mo を使う予定が無い人（層2の話がそのまま当てはまらない）

• テーマの翻訳を直したい人。関数名や読み込みの作法が違うので、この記事の手順はプラグイン限定です

• Plugin Check を通した完成形のレポートが欲しい人。私の記録では未完了です

• 翻訳の「質」（訳語の自然さ）を扱いたい人。この記事は「仕組みが動いているか」の話だけ

この記事で持ち帰れるもの一覧

有料部分に入っているのは次の通りです。

1. 5層を順に潰す6ステップの手順（各ステップに私の実測数字と、そこで踏んだ穴）

2. 日本語の棚卸しコマンド（PHP／JSを分けて数える。翻訳関数を通っていない直書きだけを炙り出す）

3. コードテンプレ4種（プラグインヘッダ＋load_plugin_textdomain／wp_localize_script で渡すJS文言／プレースホルダ置換の小さなJSヘルパ／_x() で既定値をロケール別に返す）

4. 翻訳呼び出しの1対1突合表の作り方（旧版の日本語表示と新版の .mo 適用後の表示を機械的に照合する）

5. 導入先の版確認手順（更新通知が出ないときの置き換え・マルチサイトの注意・「存在しないページでも ver= が取れる」罠の回避）

6. つまずき切り分け表（症状から層を引く）

7. 公開前チェックリスト（私が実際に通した項目）

動作確認済みの環境は、WordPress 7.1（自サイト2つ・うち1つはマルチサイト）、2026年9月7日と14日の実作業です。細かい条件は⑥に書きます。