WordPress プラグインの多言語対応
WordPress プラグインを多言語対応する方法の覚書。
WordPress の多言語対応 API
WordPress には多言語対応の為に以下の API を用意している。
load_plugin_textdomain_e__
load_plugin_textdomain はテキスト領域と文字列リソースを格納したディレクトリを指定する。WordPress のバージョンによって引数の数が異なるようだが、現行の 2.8.x 系の引数は 3 種類となる。
第一引数にはテキスト領域を指定する。ここにはプラグイン名を入れておくのが無難。後述する _e や __ でも識別子として使用するため、なんらかの変数に入れて流用するのが好ましい。
第二引数は特別な事情がない限り false を指定。第三引数には文字列リソースの置かれたディレクトリのパスを指定する。このパスはプラグインのディレクトリからの相対指定で良いとの事。
プラグインのディレクトリ名が test-plugin で文字列リソースをその下の languages に格納しているなら test-plugin/languages を指定する。万全を期すなら以下のようにするよと良い。
<?php
$lang = dirname( plugin_basename( __FILE__ ) ) . "/languages";
load_plugin_textdomain( "test-plugin", false, $lang );
?>_e と __ について。これらは翻訳対象となる文字列を置き換えるための API。_e は表示用で __ が関数などの引数に指定する事を想定している。_e は echo("文字列")、__ は文字列を返す関数とイメージするば理解しやすい。_e と __ はともに第一引数へ翻訳される文言、第二引数にテキスト領域を指定する。
プラグインの実行環境に対応した文字列リソースがあればそれを、無ければ第一引数の文字列がそのまま使用される。第二引数には load_plugin_textdomain に指定したテキスト領域の識別子を指定する。この引数を省略した場合は WordPress 標準の文字列リソースが検索される。
多言語対応の準備
はじめにプラグインの初期化部分に load_plugin_textdomain の呼び出しを追加する。この関数の呼び出しは文字列リソースの読み込み前に実行されなければならない。よってプラグインをクラス化しているならコンストラクタで呼び出すと安全。
次にプラグインの処理で翻訳の必要な文字列を _e と __ に置き換えておく。例えば以下のような処理があってデフォルトの文字列を英語にする場合、
<?php
function onAdminMenu()
{
add_options_page( "Test Plugin の設定", "Test Plugin", 8, basename(__FILE__), array( &$this, "onOptionPage" ) ) ;
}
function printTest()
{
?>
<p>テキストです。</p>
<?php
?>
}以下のようにする。
<?php
$textDomain = "testplugin";
function onAdminMenu()
{
add_options_page( __( "Test Plugin Option", $textDomain ), "Test Plugin", 8, basename(__FILE__), array( &$this, "onOptionPage" ) ) ;
}
function printTest()
{
?>
<p><?php _e( "It is text.", $textDomain ); ?></p>
<?php
}
?>元となる日本語の文字列はテキスト ファイルなどにメモしておき、日本語用の文字列リソースを作成する際にコピペしやすくしておく。
Poedit のセットアップ
プラグインの PHP スクリプト側の準備が完了したら、多言語対応する為の文字列リソースを作成してみる。
この作業には Poedit というツールを使用する。以下のページに様々な OS 向けのプログラムが公開されているのでダウンロードしておく。この記事では Windows 版を選択。
Windows 版のプログラムはインストーラー形式なので先にセットアップしておく。セットアップ後にユーザー名とメールアドレスを入力する事になるが、これは文字列リソースの更新者情報などに使用されるようだ。
セットアップが完了したら Poedit の UI を日本語化する。
Poedit を起動してメイン メニューから「File」→「Preferences...」と選択すると設定ダイアログが表示されるので、その中の「Personalize」ページにある「Change UI language」ボタンを押す。すると表示用の言語リストが表示されるので「Japanese」を選択する。
Poedit による翻訳作業
Poedit では文字列リソースをカタログと呼び、それは .po という拡張子を持つファイルとして保存される。以降の説明では Poedit にならい文字列リソースをカタログと呼ぶ。
Poedit を起動してメイン メニューから「ファイル」→「新規カタログ...」を選ぶとカタログ ファイルを作成するための設定ダイアログが表示される。
今回は日本語の例なので「情報」ページの内容は上記のようになる。「キーワード」ページでは翻訳対象となる部分を PHP スクリプト内から検索するための語句を指定する。WordPress プラグインの場合は _e と __ 関数がそれにあたるので関数名をそのまま設定しておく。
もう一つ「パス」というページがある。ここでは翻訳対象となる PHP ファイルを格納しているフォルダのパスを設定する。
全ての設定を終えてダイアログの OK ボタンを押すとカタログ ファイルの保存先を尋ねられる。翻訳対象となる WordPress プラグインのフォルダか、そのサブフォルダを開き プラグイン名-言語名.po という名前で保存する。
プラグインによってはフォルダ直下にカタログを置いているようだ。しかし私はサブ フォルダを掘りたいので今回は languages というサブフォルダに保存。プラグインの PHP ファイル名が wp-imageomap.php なので、カタログ ファイル名は wp-imageomap-ja.po とした。
保存先を設定すると PHP ファイルの解析が開始される。解析が完了すると以下のダイアログが表示される。
ダイアログには PHP ファイルから検出した翻訳対象となる原文のリストが表示される。「OK」と「アンドゥ」というボタンがあるが、内容に問題が無ければ「OK」ボタンを押して解析を完了する。
これらの手順を終えるとようやく編集画面が表示される。なおタイトル バーに表示されるパスに開発環境のユーザー名が入っていたのでモザイクを掛けている。
上段のリストから原文を選ぶと連動して下段が更新される。下段は更に二段構成になっていて上段が原文、下段が対訳に対応している。対訳部分に文字入力を行うとリスト側も変化する事が確認できる。
このように原文の対訳を作成してゆく。全ての翻訳が完了したらメイン メニューから「ファイル」→「保存」を選択する事でカタログファイルが保存される。この際、カタログ ファイルと共に .mo というバイナリ ファイルも作成される。実際に PHP スクリプトから文字列リソースとして読み込まれるのはこちらとなる。
ちなみに .po は PO (Portable Object File) ファイル、.mo が MO (Machine Object File) ファイルで前者が編集用、後者がマシンという名の通りシステムが読み取るためのものとなる。プラグインとしては MO ファイルを同梱するだけで良いそうだが、第三者が未対応言語の翻訳を行ってくれる可能性があるので PO ファイルも付けた方が親切。
カタログ ファイルの注意点
保存されたカタログ ファイルをテキスト エディターで開くと、翻訳対象 PHP ファイルのパス文字列が大量に書かれていることを確認できる。
これは Poedit が PHP ファイルを解析した結果である。しかしそのままにしておくと MO ファイルにもパスが埋め込まれるため、プラグインに同梱すると開発者の個人情報が公開される危険性がある。
そこで、テキストエディタで PO ファイル内のパス文字列を置換しておく。例えば PHP ファイルのパスが C:\wordpress\wp-content\plugins\wp-imageomap\wp-imageomap.php で PO ファイルが C:\wordpress\wp-content\plugins\wp-imageomap\languages\wp-imageomap-ja.po ならば、PHP のパスの C:\wordpress\wp-content\plugins\wp-imageomap\ 部分を ../ に置換して ../wp-imageomap.php という相対パスにする。
パス区切り文字については Windows 版 Poedit だと \を使用するが、他のプラットフォームでは / の方が一般的なので、相対パス置換と一緒に直しておく。Poedit を起動して置換後のカタログを開いてから保存すれば MO ファイルにも修正が反映される。
翻訳の確認
全ての手順が正しくおこなわれれば、プラグインの表示が日本語環境では日本語、それ以外は _e や __ 関数の第一引数に指定された文言になることを確認できるはず。