JavaScript でも WordPress を国際化したい

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

## プラグインの作成

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

`main.js`

```JavaScript
alert( 'Hello!' )
```

`functions.php`

```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 にインストールして有効化します。

<img width="1552" alt="Screenshot 2019-03-31 21.08.54.png" src="https://qiita-image-store.s3.amazonaws.com/0/125062/509255c8-7b39-ab8e-87f5-83171979e6fb.png">

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

## 国際化する

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

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

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

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

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

```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`](https://developer.wordpress.org/reference/functions/wp_set_script_translations/) という関数を呼ぶようにします。これにより WordPress が生成する HTML 内に辞書ファイルが展開されるようになり JavaScript から辞書が利用可能になります。

```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' ]
  );

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

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

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

`main.js`

```javascript
const __ = wp.i18n.__

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

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

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

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

<img width="1552" alt="Screenshot 2019-03-31 21.08.20.png" src="https://qiita-image-store.s3.amazonaws.com/0/125062/1d7e295a-d0ed-4c58-10be-909813bf5f33.png">

## まとめ

WordPress プラグインの JavaScript のコードに含まれるテキストの国際化について解説しました。テーマについてもほぼ同じ手順で対応ができます。より詳細については、[公式ドキュメント](https://make.wordpress.org/core/2018/11/09/new-javascript-i18n-support-in-wordpress/)を参照してください。

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

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