WordPress: load_theme_textdomain()とload_plugin_textdomain()関数を少し詳しく解説してみる

WordPressでテーマやプラグインを多言語化するとき、load_theme_textdomain()やload_plugin_textdomain()という関数を使用します。
今回は、これらの関数について調べてみました。

翻訳データ読み込み関数

WordPressのload_theme_textdomain()関数とload_plugin_textdomain()関数は、現在のロケールに対応する翻訳データファイルをWordPressプログラム内に読み込む関数です。

ロケールは日本語なら 'ja'、英語なら 'en_US'　というように言語ごとに割り当てられている文字列です。
ロケールは同じ言語でもいくつかの表記方法があります。日本語は 'ja'の他に'ja_JP'などがあります。

この状況は少し使いにくいことから、WordPressは言語ごとに使用できるロケールを定義しています。
定義されているロケールについては、次の記事を参考にしてみてください。

WordPress: WordPressで使用できるロケール名一覧を取得してみる

また翻訳データファイルの作成方法については、次の記事で紹介しているので参考にしてみてください。

Poeditの使い方。新規から作成してmoをテーマやプラグインに適用する方法

テーマ用翻訳データ読み込み関数

テーマ用翻訳データ読み込み関数は、通常のテーマ用と子テーマ用の二種類あります。

通常のテーマ用はload_theme_textdomain()関数で、子テーマ用はload_child_theme_textdomain()関数です。

通常のテーマ用:load_theme_textdomain( )

load_theme_textdomain()関数は、テーマ用の翻訳データ読み込み関数です。

構文

load_theme_textdomain( $domain, $path = false )

$domain:テキストドメイン
$path: 翻訳データが格納されているディレクトリ

この関数は、次の順番で翻訳データファイルを検索します。

/wp-content/languages/themes/$domain-言語ロケール.mo
$path/言語ロケール.mo
$pathがfalseのとき、テーマのパス/言語ロケール.mo

$domainはload_theme_textdomain()関数の第一引数です。

見ての通り、①のファイルが存在するときは、引数$pathは考慮されません。
テーマを公式ディレクトリに登録すると、第三者がGlotPressというシステムを使用して翻訳を提案できるようになります。
このシステムで生成された翻訳データファイルは、①の位置に配置されます。

公式ディレクトリに登録した場合、テーマ作成者が翻訳データを更新して②に配置しても適用されないので注意が必要ですね。

ちなみに公式ディレクトリに登録する場合は、テーマ名（/wp-content/themesに配置されるときのディレクトリ名）をテキストドメインとして指定します。
GlotPressが生成する.moファイルは、このディレクトリ名を元に名前つけされるためです。

公式ディレクトリに登録しない場合は、プラグイン等と重複しなければなんでもＯＫです。

■使用例

add_action( 'after_setup_theme', 'my_load_theme_textdomain' );
function my_load_theme_textdomain(){
global $my_theme_textdomain;
$my_theme_textdomain = 'my_theme';
load_theme_textdomain( $my_theme_textdomain );
}
function echo_my_text(){
global $my_theme_textdomain;
_e( 'hello' , $my_theme_textdomain );
}

AFFS Simple Code Viewer

Copy

翻訳ファイルの読み込みは、after_setup_themeアクションでおこなうのが作法のようですね。
after_setup_themeアクションはプラグインファイルとテーマのfunction.phpを実行した後に呼び出されます。
プラグインやテーマでロケール取得のフィルターを掛けている可能性があるので、確実に実行するためにもこのタイミングが良いようです。

_e()などの翻訳関数については、次の記事を参考にしてください。

WordPress: __()や_e()だけじゃない。翻訳関数の一覧

子テーマ用:load_child_theme_textdomain( )

load_child_theme_textdomain()関数は、子テーマ用の翻訳データ読み込み関数です。

構文

load_child_theme_textdomain( $domain, $path = false )

$domain:テキストドメイン
$path: 翻訳データが格納されているディレクトリ

この関数は、次の順番で翻訳データファイルを検索します。

/wp-content/languages/themes/$domain-言語ロケール.mo
$path/言語ロケール.mo
$pathがfalseのとき、子テーマのパス/言語ロケール.mo

この関数は$pathがfalsenoとき、内部でload_theme_textdomain( $domain , 子テーマのパス)を呼び出しています。
そのため、load_theme_textdomain()関数とほぼ同じです。

親テーマと同じテキストドメインを指定すると、翻訳データが結合されます。
ただし同じキーワードに対する翻訳は、上書きされません。
つまり、先に読み込まれた翻訳が残ります。

子テーマの翻訳を優先させたいときは、親テーマよりも先に読み込み関数を実行しないといけません。
そのため親のコードを見て、子テーマのコードを作成する必要があります。

具体的には、親テーマがアクションフックを使用しているなら、同じアクションで呼び出す。
使用しないでfunction.phpなどで直接呼び出しているなら、同じように直接呼び出します。

なお、function.phpは、子テーマ→親テーマの順で呼び出されます。
そのため関数の実行順は気にしなくて大丈夫です。

フィルターとアクション

load_theme_textdomain()関数および、load_child_theme_textdomain()関数はいくつかのフィルターを呼び出しています。

タイプ	名前	引数。()は初期値	内容
フィルター	theme_locale	ロケール名(現在のロケール名)、テキストドメイン	ロケール名を変更できます
フィルター	override_load_textdomain	真偽値(false)、テキストドメイン、翻訳ファイルのパス	翻訳ファイルを読み込むかどうかを決定します。フィルターがtrueを返すと翻訳ファイルの読み込みをおこなわないで、関数を終了します。
アクション	load_textdomain	テキストドメイン、翻訳ファイルのパス	読み込み前の通知
フィルター	load_textdomain_mofile	翻訳ファイルのパス、テキストドメイン	読み込み前に翻訳ファイルのパスを変更できます

各関数は二つのディレクトリを検索します。
その結果、theme_localeフィルター以外は最大2回呼び出されます。

1回目のoverride_load_textdomainフィルターがtrueを返した場合、その時点で関数は終了します。
二つ目のディレクトリは検索されません。

プラグイン用翻訳データ読み込み関数

プラグイン用の翻訳データは、load_plugin_textdomain()関数で読み込みます。

load_plugin_textdomain()

構文

load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path = false )

$domain:テキストドメイン
$deprecated: 常にfalseが推奨
$plugin_rel_path: 翻訳データが格納されているディレクトリ

この関数は、次の順番で翻訳データファイルを検索します。

/wp-content/languages/plugins/$domain-言語ロケール.mo
引数から求められたパス/$domain-言語ロケール.mo

引数から求められたパスは、次のように求められます。

$plugin_rel_pathがfalseでないとき、WordPressのホームディレクトリ/wp-content/plugins/$plugin_rel_path が引数から求められたパスになります。

$plugin_rel_pathがfalseで$deprecatedがfalseでないとき、、WordPressのホームディレクトリ/$deprecatedが引数から求められたパスになります。

$plugin_rel_pathと$deprecatedが共にfalseのとき、WordPressのホームディレクトリ/wp-content/plugins/が引数から求められたパスになります。

パス指定については、テーマ用のload_theme_textdomain()関数および、load_child_theme_textdomain()関数はフルパスでした。
プラグインの場合は、相対パスなので注意が必要です。

load_plugin_textdomain()関数はload_theme_textdomain()関数と同じように、①のファイルが存在するときは、引数$plugin_rel_pathおよび$deprecatedは考慮されません。
理由も同じで、プラグインを公式ディレクトリに登録すると、第三者がGlotPressというシステムを使用して翻訳を提案できるようになります。
このシステムで生成された翻訳データファイルは、①の位置に配置されます。

公式ディレクトリに登録した場合、プラグイン作成者が翻訳データを更新して②に配置しても適用されないので注意が必要です。

なお公式ディレクトリに完全に移行しない限り、load_plugin_textdomain()関数を第二引数以降を省略して呼び出すことはほとんどありません。
省略すると、プラグインの親パス（/wp-content/plugins/）が参照されます。
プラグインの翻訳ファイルを親パスに設置することはほとんど無いので、$plugin_rel_pathを省略するケースもほとんど無いのです。

■使用例

add_action( 'after_setup_theme', 'my_load_theme_textdomain' );
function my_load_theme_textdomain(){
global $my_plugin_textdomain;
$my_plugin_textdomain= 'my_plugin';
$plugin_dir = dirname( plugin_basename( __FILE__ ) );
load_plugin_textdomain( $my_plugin_textdomain, false, $plugin_dir );
}
function echo_my_plugin_text(){
global $my_plugin_textdomain;
_e( 'hello' , $my_plugin_textdomain);
}

AFFS Simple Code Viewer

Copy

プラグインもテーマと同じようにafter_setup_themeアクションで翻訳ファイルを読み込みます。

load_plugin_textdomain()に渡す引数$plugin_dirは、プラグインのディレクトリを含みます。
プラグインのディレクトリは、dirname( plugin_basename( __FILE__ ) ) で取得します。

load_muplugin_textdomain()

load_muplugin_textdomain()関数は、Must Use Pluginsを読み込みます。

Must Useは必ず使うという意味なので、Must Use Pluginsは必須プラグインという意味になります。
必須プラグインは、/wp-content/mu-plugins に配置されます。

構文

load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' )

$domain:テキストドメイン
$mu_plugin_rel_path: 翻訳データが格納されているディレクトリ

この関数は、次の順番で翻訳データファイルを検索します。

/wp-content/languages/plugins/$domain-言語ロケール.mo
/wp-content/mu-plugins/$mu_plugin_rel_path/$domain-言語ロケール.mo

あまり使う機会が無いので、これ以上は解説しません。

フィルターとアクション

テーマ用の読み込み関数と同じように、load_plugin_textdomain()関数および、load_muplugin_textdomain()関数はいくつかのフィルターを呼び出しています。

タイプ	名前	引数。()は初期値	内容
フィルター	plugin_locale	ロケール名(現在のロケール名)、テキストドメイン	ロケール名を変更できます
フィルター	override_load_textdomain	真偽値(false)、テキストドメイン、翻訳ファイルのパス	翻訳ファイルを読み込むかどうかを決定します。フィルターがtrueを返すと翻訳ファイルの読み込みをおこなわないで、関数を終了します。
アクション	load_textdomain	テキストドメイン、翻訳ファイルのパス	読み込み前の通知
フィルター	load_textdomain_mofile	翻訳ファイルのパス、テキストドメイン	読み込み前に翻訳ファイルのパスを変更できます