Gutenbergの国際化対応手順（5.8対応）

先日、人生初のWordPress公式プラグイン Low-Key ToolBar をリリースしました。その過程で国際化対応した際に、Gutenberg部分の国際化にかなり手間取ったので、その方法をまとめました。

ネットで検索すると情報は沢山でてくるのですが、Gutenbergの初期の頃の情報だったり、情報が分散していて非常に分かりにくいといった状況でした、この記事では現時点（WordPress 5.8）で使える方法をまとめてあります。

1 プラグイン国際化の手順
2 1.翻訳ファイルを入れるフォルダを作る
3 2.テキストドメインを決める
4 3.プラグインヘッダーにText DomainとDomain Pathを設定
5 4.翻訳ファイルの読み込み処理
6 5.翻訳箇所を翻訳関数で書き換え
7 6.翻訳ファイルの準備
8 POファイルからjsonを作成
9 公式プラグインにするならPoeditなどは不要

プラグイン国際化の手順

全体の流れは下記のようになります。

国際化の手順

翻訳ファイルを入れるフォルダを作る
テキストドメインを決める
プラグインヘッダーにText DomainとDomain Pathを記入
翻訳ファイルの読み込み処理を記述
翻訳箇所を翻訳関数で書き換え
翻訳ファイルの作成（Poedit）
POファイルからJSONを作成

基本的な流れはPHPベースのプラグインとほとんど同じですが、4,5,7でGutenberg（JavaScript）に対応するための追加作業が必要になってきます。

では、作業を進めていきましょう。

1.翻訳ファイルを入れるフォルダを作る

翻訳用のPOファイルやJSONファイルを入れるためのフォルダを作ります。プラグインディレクトリ直下にlanguagesという名前のフォルダ作るのが一般的です。

ちなみに私が作ったプラグイン、Low Key ToolBarでは下図のようにプラグインディレクトリ直下に配置しています。

2.テキストドメインを決める

テキストドメインには他のプラグインと同じにならないようなユニークな名前を指定します。といっても、普通はプラグイン名とほぼ同じになると思います。

Low Key ToolBar では low-key-toolbar としました。

3.プラグインヘッダーにText DomainとDomain Pathを設定

プラグインのメインファイルのヘッダーにText DomainとDomain Pathを記入します。

Text Domain→ 2.で設定したテキストドメイン
Domain Path→1.で作成したフォルダへのパス

Low Key ToolBarの場合は次のようになります。

/**
 * Plugin Name:       Low-Key Toolbar
 * Description:       This plugin add translucent option to block editor toolbar.
 * Requires at least: 5.7
 * Requires PHP:      7.0
 * Version:           1.0.0
 * Author:            Makoto Nakao
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       low-key-toolbar
 * Domain Path        /languages
 *
 */

4.翻訳ファイルの読み込み処理

ここからPHPと変わってくる部分です。

PHPのみのプラグインインならload_plugin_textdomain()だけでよいのですが、Gutenberg（JavaScript）に対応するためにはwp_set_script_translations()という関数も追加する必要があります。

両者をまとめると下記のようなコードになります。

function my_load_plugin_textdomain() {

	load_plugin_textdomain(
		'low-key-toolbar', // Text Domain
		false,
		dirname( plugin_basename( __FILE__ ) ) . '/languages' // languagesフォルダへのフルパス
	);

}
add_action( 'plugins_loaded', 'my_load_plugin_textdomain' );


function my_set_script_translations() {
		wp_set_script_translations(
			'low-key-toolbar-script', // JavaScriptのハンドル名
			'low-key-toolbar', // Text Domain
			dirname( plugin_basename( __FILE__ ) ) . '/languages' // languagesフォルダへのフルパス
		);
}
add_action( 'enqueue_block_editor_assets', 'my_set_script_translations' );

JavaScriptのハンドル名はブロックエディタ用に読み込むJavaScriptのハンドル名になります。

5.翻訳箇所を翻訳関数で書き換え

翻訳したい箇所を翻訳関数（__()やe_()など）で書き換えていきます。翻訳関数は__(翻訳したい文字列, テキストドメイン）という形式になります。

Gutenbergの場合、翻訳関数は__()だけで事足りることがほとんどだと思います。また、ソース冒頭で@wordpress/i18nを読み込んでおくことも忘れないように。

以下にJavaScriptのソース例を掲載しておきます。

import { __ } from '@wordpress/i18n'; // 翻訳関数のコンポーネントを読み込む
/* 省略 */

	return (
		<Fragment>
			<PanelBody>
				<RangeControl
					label={__('Opacity', 'low-key-toolbar')} // ラベルに翻訳関数を適用
					value={opacity}
					initialPosition={opDef}
					min={0.1}
					max={1}
					step={0.1}
					onChange={(value) => setOpacity(value)}
				/>
				<RangeControl
					label={__('Scale', 'low-key-toolbar')} // ラベルに翻訳関数を適用
					value={scale}
					// allowReset={true}
					initialPosition={scaleDef}
					min={0.1}
					max={1}
					step={0.1}
					onChange={(value) => setScale(value)}
				/>
/* 省略 */

6.翻訳ファイルの準備

これでプログラム側の準備は完了したので翻訳ファイルを作成していきます。翻訳ファイルの作成にはPoeditをつかいました。下記の公式サイトからダウンロードできます。この記事を書いた時点でのバージョンは3.0です。

Poedit Translation Editor — Poedit

新規作成する

Poeditを起動するとウェウカム画面が表示されますが、POTファイルがない新規の状態からスタートする場合、この画面のメニューは使えません。閉じておきましょう。

有料版は機能が豊富

上の画面に「WordPressのテーマ・プラグインを翻訳」というメニューがありますが、これは有料版の機能です。便利な機能がたくさんあるので大規模なプラグインやテーマを翻訳したい場合は有料版にした方が作業がはかどると思います。

メニューバーのファイルから「新規…」を選択します（Mac版の場合）。すると次のような画面が表示されるので、言語が日本語でよければそのままOKをクリックします。

ここで一旦保存します。メニューからファイル→保存で保存するのですが、保存場所とファイル名は決まっているので注意しましょう。ここを間違えると翻訳が適用されないので注意してください。ここはハマりやすいポイントです。

保存場所→翻訳ファイルを置くフォルダ
この記事の例では最初に作った/languagesフォルダ
ファイル名→テキストドメイン-ロケール名
この記事の例ではlow-key-toolbar-ja

ロケール名は翻訳する言語のよって変わります。日本語ならjaです。

この設定で保存するとlanguagesフォルダ内にPOTファイルとMOファイルが保存されます。

ソースから抽出

ファイルが保存できたらソースから翻訳箇所を抽出していきます。

まずは「ソースから抽出」をクリックしましょう。

ソースのパスを設定する画面が表示されるので、パスにプラグインのルートフォルダを指定します。

また、ブロックを開発している場合、node_modulesフォルダがプラグインフォルダ内にあると思います。こいつを抽出対象に含めてしまうと無駄に時間がかかるので必ず除外パスに指定しておきましょう。

上記のような設定をすると次の画像のようになっているはずです。有料版への催促がでますがここは無視します。

次に「翻訳の特性」タブをクリックして、プロジェクト名を指定します。個人開発なら指定しなくてもよいと思います。

最後は「ソース中のキーワード」タブをクリックして、キーワード（翻訳関数）を追加していきましょう。

ブロックエディタしか対象でない場合は__()だけで十分ですが、PHPも含めるなら_e()などソース内で使っている翻訳関数を全て追加する必要があります。

ちなみに有料版になるとこの部分が既に登録されているようです。

ここまで設定が完了したら「OK」をクリックしましょう。

翻訳作業

設定が適切だと、下図のように抽出結果の一覧が表示されます。あとはそれを見ながら対訳のところに適切な翻訳を設定していきます。

全てを手作業で行う必要は無く、右上の「事前翻訳」をクリックすると一般的なものは自動的に翻訳が割り当てられます。有料版になるとその翻訳精度がさらに上がるようです。

以上で翻訳ファイルの作成は完了です。PHPのみの場合はこれで完了ですが、ブロックエディタに対応する場合はJSON形式の翻訳ファイルも用意する必要があります。

残念ながらPoeditでがJavaScriptに対応したjsonは作ってくれません。別作業となります。

POファイルからjsonを作成

POファイルからjsonを作成するためにはpo2jsonというnpmパッケージを使う必要があります。

まずはターミナルからpo2jsonをインストール。

npm install po2json

po2jsonは次のように指定して実行します。-f jedは出力するフォーマットの指定です。

po2json POファイルのパス パスを含めた変換したファイル名 -f jed

ファイル名は必ず 「テキストドメイン名」-「ロケール」-「jsのハンドル名」.json というファイル名にしてださい。これを間違うと翻訳が適用されません。私はここでかなりハマりました…

翻訳ファイルの保存先がlanguagesフォルダ、テキストドメインがlow-key-toolbar、jsのハンドル名がlow-key-toolbar-scrpitの場合、次のようになります。

po2json languages/low-key-toolbar-ja.po languages/low-key-toolbar-ja-low-key-toolbar-script.json -f jed

これを実行するとlanguagesフォルダ内にlow-key-toolbar-ja-low-key-toolbar-script.jsonというファイルが作られます。

あとは、きちんと日本語が適用されているか確認して問題なければOKです。

公式プラグインにするならPoeditなどは不要

ここまで色々説明しておいて何ですが、公式プラグインにする場合はPoeditを使ったりJSONを作って翻訳ファイルを用意しておく必要はありません。翻訳作業はtranslate.wordpress.orgというサイト上でオンラインで行うことができます、というかここできちんと登録しないと翻訳ファイルが適用されません。

とはいえ、翻訳部分の実装が正常に機能するか確認する意味で、POTファイルやMOファイルを作ることは必要かなと思います。

Gutenbergの国際化対応の手順（5.8対応）