はじめてJSONファイル（JED 1.x）を作った時のメモ

説明

先日、サイト間で投稿内容をコピー＆ペーストするためのプラグイン「Paste JSON text」をブロックエディターに対応させた。このプラグインでは、JavaScriptファイルで翻訳テキストを使用しており、はじめてJEDファイルを作成。その作業のポイントを忘れないように残すことにした。

WP-CLIをインストール

ブロックエディター向けのプラグインで翻訳ファイルを使う方法は「国際化」に記載されている。そこにはJavaScriptファイル向けの翻訳ファイルはJED 1.x JSONフォーマットとなり、WP-CLIで作成する方法が紹介されている。というわけで、まずはWP CLIのインストールから（対象ははWindows環境とする）。

「WP-CLI公式サイト」にアクセスし、「wp-cli.phar」をダウンロード。PHPがインストールされたディレクトリ（ここではC:\Program Files (x86)\php）にコピーする。続いて、同じディレクトリに以下の内容で「wp.bat」を作成する。

@echo off
php "C:/Program Files (x86)/php/wp-cli.phar" %*

Windows環境の場合、パスが通っていればこれでWP-CLIコマンドが使用可能になる。

まずは.potファイル

作業の流れは次の通り。

1. WP-CLIコマンドを使って.potファイルを作成
2. .potファイルをコピーし、対象言語の.poファイルを作成
3. WP-CLIコマンドを使って.jsonファイルを作成

.potファイルの作成は、コマンドプロンプトを開いてプラグインのディレクトリに移ってから行う。作成する.potファイルの名前にはJavaScriptファイルの__関数で指定したドメイン名（ここではpaste-json-text-js）を指定する。

wp i18n make-pot ./ languages/paste-json-text-js.pot

なお.potファイルのパス名で指定したディレクトリがない場合、「管理者」でコマンドプロンプトを開いているならディレクトリは作成されるが、通常のコマンドプロンプトではディレクトリは作成されないので要注意。

実際に作成された.potファイルを見てみる。そこにはJavaScriptファイル内に記述された翻訳テキストだけでなく、プラグインのPHPファイルのヘッダーに記述された「Plugin Name」や「Description」といったプラグイン情報も翻訳用として抽出されている。

このように.potファイルの作成はいたって簡単だが、JavaScriptファイルの変更に伴って.potファイルを作り直していると、.potファイルファイルは更新されるがその中にJavaScriptファイル内の翻訳テキストが出力されない問題が発生した。原因を探すべく作業を振り返ると、MinifyしたJavaScriptファイルを作っており、試しにそのファイルを削除してみると.potファイルにJavaScriptファイルの翻訳テキストが含まれるようになった。

とりあえず問題の対処法はわかったのだが、毎回MinifyしたJavaScriptファイルを削除するのは面倒くさい。MinifyしたJavaScriptファイルがあっても.potファイルが更新できないか試行錯誤したところ、「--domain」オプションを追加することで問題が回避できた。

wp i18n make-pot --domain=paste-json-text-js ./ languages/paste-json-text-js.pot

.potファイルをコピーして.poファイルを

次は.potファイルをコピーして.poファイルを作成する。.poファイルのファイル名は目的の言語によって変わり、日本語の場合は「ja」となる。

copy languages\paste-json-text-js.pot languages\paste-json-text-js-ja.po

テキストエディター等で.poファイルを開き、まずは赤字で示す「Language」の行を追加。次に青字の箇所を適宜書き換える。

"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: ja\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2022-03-04T02:22:18+00:00\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"

1つの翻訳情報は、原文が「msgid」に翻訳文が「msgstr」に記述される（日本語以外の言語では他のキーワードも使用する）。

msgid "Copy content"
msgstr ""

翻訳したい箇所の「msgstr」行を書き換えたら、必ず「UTF-8（BOM無）」で保存する。Windows環境では「シフトJIS」で保存してしまうことがあり、その場合は次のステップで作成する.jsonファイルの中身が空になるといった問題が発生してしまう。

.poファイルから.jsonファイルを

.jsonファイルの作成もWP-CLIコマンドを使用する。

wp i18n make-json languages/paste-json-text-js-ja.po --no-purge

第2パラメータが「make-pot」ではなく「make-json」となり、続いて.poファイルのパス名、オプションの「--no-purge」を指定する。「--no-purge」を指定しないと、.poファイルから前ステップで編集した翻訳情報がなくなり、.moファイルが作成されるてしまう。そんなことにならないよう、忘れずに「--no-purge」を指定しよう。

作成された.jsonファイルの名前は「{domain}-{locale}-{md5}.json」の書式になり、今回は「paste-json-text-js-ja-3da844d31b7b52b6743101da89ee5368.json」となった。この{md5}の内容は翻訳ファイルを適用するJavaScriptファイルの相対パスのMD5ハッシュ値であり、このプラグインの場合はプラグインがあるディレクトリ直下のassets/js/paste-json.jsファイルが翻訳対象となるため、以下によって求めることができる。

$md5 = md5( 'assets/js/paste-json.js' );

このことから.jsonファイルの作成後、JavaScriptファイルのパス名を変更するとMD5ハッシュ値が変わってしまう。結果的に.jsonファイルとマッチしなくなり、翻訳されなくなってしまう。JavaScriptファイルのパス名を変更した場合は、忘れずに.jsonファイルを作り直そう。

.jsonファイルの名前は「{domain}-{locale}-{md5}.json」のほか「{domain}-{locale}-{handle}.json」も読み込み対象となっている。「{handle}」はPHP側でJavaScriptファイルをエンキューする際に使用する wp_enqueue_script関数の第1パラメータであり、この.jsonファイルはパス名に変更に依存せず、また.jsonファイルの名前でどのJavaScriptファイルが対象になっているの識別しやすい。JavaScriptファイルの相対パスとハンドルをうまく管理する方法はないだろうか。

今回使ったWP-CLIコマンドは実に多機能である。翻訳ファイルに関連するWP-CLIコマンドのオプションについては「wp i18n | WP-CLI Command」で詳しく解説されているので目を通しておこう。