JavaScript でも WordPress を国際化したい

この記事では WordPress のプラグイン・テーマの JavaScript のコードに含まれるテキストを国際化する方法について解説します。

プラグインの作成

今回は JavaScript の国際化(i18n)の例として、ページ表示時に window.alert 呼び出すだけの WordPress プラグイン i18n-alert を作成します。スクリプトを enqueue するときに、 wp-i18n という国際化のためのライブラリ （WordPress 5.0 以降に組み込まれています！） を依存関係に記述する必要があるので忘れないようにしましょう。

main.js

alert( 'Hello!' )

functions.php

<?php
/**
 * Plugin Name: I18n Alert
 * Text Domain: i18n-alert
 * Version:     0.1.0
 */

add_action( 'wp_enqueue_scripts', function() {
  wp_enqueue_script(
    'my-script-handle',
    plugins_url( '/main.js', __FILE__ ),
    [ 'wp-i18n' ]
  );
} );

プラグインを WordPress にインストールして有効化します。

OK、ちゃんとアラートが表示さていますね。

国際化する

それではプラグインの国際化を進めていきます。次の 3 ステップが必要です。

1. JavaScript 用の辞書ファイルを用意する
2. 辞書ファイルの位置を指定する (PHP 側)
3. 翻訳関数を適用する (JavaScript 側)

1. JavaScript 用の辞書ファイルを用意する

JavaScript 用の辞書ファイルは、JSON 形式で用意します。以下のような JSON ファイルを作成します。これは、Jed と呼ばれる形式の JSON で、国際化のための辞書データの構造を持っています。

languages/i18n-alert-ja-my-script-handle.json

{
  "domain": "i18n-alert",
  "locale_data": {
    "i18n-alert": {
      "": { "domain": "i18n-alert" },
      "Hello!": ["こんにちは！"]
    }
  }
}

冗長なファイル名は WordPress が辞書ファイルを読み込むために必要で、次のルールを満たすようにします。

${domain}-${locale}-${handle}.json

${domain} はプラグインのテキストドメイン、${handle} は enqueue したスクリプトのハンドルの値を指定する必要があります。また、 ${locale} の値を変更して辞書ファイルの数を増やすことで複数の言語に対応できます。

2. 辞書ファイルの位置を指定する (PHP 側)

functions.php で wp_set_script_translations という関数を呼ぶようにします。これにより WordPress が生成する HTML 内に辞書ファイルが展開されるようになり JavaScript から辞書が利用可能になります。

<?php
/**
 * Plugin Name: I18n Alert
 * Text Domain: i18n-alert
 * Version:     0.1.0
 */

add_action( 'wp_enqueue_scripts', function() {
  wp_enqueue_script(
    'my-script-handle',
    plugins_url( '/main.js', __FILE__ ),
    [ 'wp-i18n' ]
  );

  wp_set_script_translations(
    'my-script-handle',
    'i18n-alert',
    dirname( __FILE__ ) . '/languages'
  );
} );

3. 翻訳関数を適用する (JavaScript 側)

最後に、JavaScript 側のコードで翻訳関数を適用するように変更します。

main.js

const __ = wp.i18n.__

alert( __( 'Hello!', 'i18n-alert' ) )

wp-i18n を読み込んでいるため、 window.wp.i18n というオブジェクトがグローバルに宣言されています。翻訳関数 __ を翻訳対象文字列に適用すると翻訳後の値が return され、 alert に渡されるようになります。
この翻訳関数は、PHP 側で多言語対応したことがある開発者にはおなじみの関数名ですね。これ以外の翻訳関数については、 @wordpress/i18n のドキュメントなどを参照してください。

翻訳が適用されていることを確認する

WordPress 本体の言語設定が日本語になっていることを確認しブラウザをリロードします。上記の設定が正しくされていれば、当初は英語だったアラートが日本語になっているはずです。

まとめ

WordPress プラグインの JavaScript のコードに含まれるテキストの国際化について解説しました。テーマについてもほぼ同じ手順で対応ができます。より詳細については、公式ドキュメントを参照してください。

この記事で wp-i18n という名前で enqueue して利用している @wordpress/i18n という国際化ライブラリは、ブロックエディタの Gutenberg の国際化のために同時に開発されているユーティリティですが、それ単独でも利用可能なものです。 @wordpress/i18n 以外にも、様々な面白いツールが Gutenberg の GitHub リポジトリに同梱されており、覗いてみると面白いかもしれません。

この記事で作成したプラグインのコードは以下のリポジトリとしてアップロードしています。
https://github.com/kamataryo/sandbox-wordpress-js-i18n