CakePHP3のメッセージ日本語化の設定（国際化と地域化の機能の使い方の解説）

CakePHP3の英語のメッセージを日本語に翻訳して表示する

CakePHP3にはメッセージを日本語化する機能が搭載されている

　
CakePHP3で、Bakeすることで自動生成されてくるプログラムや画面のテンプレート（HTMLファイル）に使われるメッセージの言語は英語です。
　
ですが、CakePHP3には、英語のメッセージを日本語化（多言語化）する機能があらかじめ搭載されていますので、それを利用して日本語化（多言語化）する方法を解説します。
　
　
具体的には、「/src/Locale/ja/」フォルダを作成し、その中に「default.po」という英語を日本語に翻訳する翻訳ファイルを設置すると、英語のメッセージを日本語に翻訳して表示してくれます。
　
翻訳の仕組みはシンプルなのですが、翻訳ファイル「default.po」を作成する作業は結構大変な作業なので、CakePHP3に用意されているツールを使って作成していきます。
　
　
　
CakePHP3に搭載されている日本語化（多言語化）の手順は以下のとおりです。
　

• 【コマンド実行】英語と日本語（他国語）を関連付ける辞書ファイルのベースを作成
• 【アナログ作業】辞書ファイルに英語に対応する日本語の対訳を編集する
• 【自動処理】画面表示時に、辞書ファイルにもとづき日本語を表示する

　
もう少し具体的に書くと
【コマンド実行】で「default.pot」ファイルを作成し
【アナログ作業】で「default.pot」ファイルを元に「default.po」ファイルを作成して、日本語の対訳を編集する
　
そうすると、
【自動処理】として、CakePHP3が画面を表示する際に、プログラムなどに記述されている英語のメッセージを「default.po」に書かれている日本語訳に置き換えて日本語のメッセージとして画面を表示してくれる
ということになります。
　
【コマンド実行】は、2、3分の作業。
【自動処理】は、自動処理なので特に何もしない。
　
ですが、【アナログ作業】の日本語の訳を付けていく作業は完全にアナログ作業ですので、メッセージ数が多ければ多いほど時間がかかります。
ただ、すべてのメッセージを日本語化する必要があるわけではありませんので、最低限対応が必要なところから順次進めていくといいのではないでしょうか。
　
　
それでは、以降が具体的な作業手順です。
　
　

CakePHP3でメッセージを日本語化（多言語化）するための手順の解説

辞書ファイルのベースを作成する作業

　
まず、辞書ファイルのベースを作成するためにコマンドを実行します。
　
コマンドを実行する際は、CakePHP3のアプリを作成しているルートフォルダに移動します。
　

　
　
続いて、コマンド「bin/cake i18n」を実行します。
その後は、画面の表示に応じて選択肢を入力していきます。
　

　
最後まで実行すると、「/var/www/html/example.com/src/Locale/」に、辞書ファイル「default.pot」が生成されていますので、それを確認します。
　
　

コマンドを「bin/cake i18n extract」と入力する方法もある

　
今回はコマンド「bin/cake i18n」を実行していますが、「bin/cake i18n extract」と入力する方法もあります。
　
今回は、コマンド「bin/cake i18n」を実行し、表示されるメニューの中から「E（extract）」を選択していますが、最初に入力するコマンドを「bin/cake i18n extract」とすることで、はじめから「E」を選択した状態まで進めることができます。（1工程だけスキップすることができます。）
　

　
　
また、コマンド「bin/cake i18n」を実行したときにでてくるメニューはそれぞれ以下の内容になります。
　

default.potがある場合は上書きをするかどうかの確認が追加される

　
すでに「/var/www/html/example.com/src/Locale/default.pot」ファイルが存在する場合は、下記の確認が追加されます。
上書きする場合は「y」を選択します。
もし、すでに日本語化したファイルがある場合は、「default.pot」のファイル名を変更するなどして対応してください。
　

生成された辞書のベースファイルの確認

　
コマンド「bin/cake i18n」を実行すると、「/var/www/html/example.com/src/Locale/」に、辞書ファイル「default.pot」が生成されていますので、それを確認します。
　
　
生成されているファイルは、以下のような内容です。
　

　
このファイルは、辞書ファイルのベースとなるもので、コントローラーやテンプレートファイルの中にある「__('*****')」の部分を抽出したものになります。
　
msgid "The topic has been saved."
の部分がテンプレートに記載がある英語表記のメッセージ部分で
msgstr ""
の部分が、これから日本語に翻訳したメッセージを編集する部分です。
　
　
上記の「ホーム」「使い方」「お知らせ」などは日本語が出力されていますが、それは、すでにテンプレートファイルにある「__('*****')」の部分を日本語に置き換えているためです。
　
翻訳ファイルを作成するのであれば、日本語にした箇所があるあ場合は、英語に戻した上で、改めて翻訳ファイルを作成し直すほうがいいでしょう。
　
　
また、コマンドで作成した「default.pot（default.po）」ファイルの「msgid ""」「msgstr ""」ですが、手作業でメッセージを追加していっても全く問題ありません。
　
　

翻訳ファイルのベースファイルを日本語対応のファイルに変換する

　
翻訳のベースファイル（default.pot）を、日本語対応のファイルに変換します。
　

１．日本語辞書を入れるフォルダを作成する

　
まず、日本語の辞書を入れるフォルダを作成します。
　
「default.pot」ファイルが生成されている
/src/Locale/
フォルダの中に「ja」フォルダ（もしくは、「ja_JP」フォルダ）を作成します。
　
また、日本語以外では「フランス語：fr」「ドイツ語：de」「ロシア語：ru」「イタリア語：it」などのフォルダを作成します。
　
　

２．日本語辞書ファイルを設置する

　
前項で作成した「ja」フォルダの中に、作成された「default.pot」を「default.po」にファイル名を変更して設置します。（拡張子を「.pot」から「.po」に変更します。）
　
これで設置完了です。
　
　

３．実際に日本語に変換されるかを確認する

　
前項で、設置は完了ですが、この状態では英語の翻訳となる日本語の編集をしていませんので、日本語は表示されません。
　
そのため、辞書ファイルの中の分かりやすい「Submit」などを日本語に変換してみて、画面をリロードして、日本語に変わることを確認してみてください。
　

　
　

翻訳ファイルを修正したときはキャッシュをクリア

　
翻訳ファイルを設定すると翻訳した内容はキャッシュされる場合が多々あります。
そのため、翻訳ファイルを変更したのに反映されない、ということが起こりますので、翻訳ファイルを変更した場合はその都度キャッシュをクリアすることをオススメします。
　
キャッシュのクリア方法は、ルートフォルダでコマンド「bin/cake cache clear_all」を実行する方法が一番簡単で確実です。
詳しくは、下記の記事を参照してください。
CakePHP3、CakePHP4のキャッシュをクリアする方法「bin/cake cache clear_all」を使う
　
　

コマンド「bin/cake i18n」実行時に発生するエラー内容の確認方法

　
コマンド「bin/cake i18n」を実行して、テンプレートを作成する時にエラーが発生すると、下記のようなエラーメッセージを見ることがあります。
　
7 marker error(s) detected.
=> Use the --marker-error option to display errors.
　
この場合は、エラーメッセージを表示する場合は下記の通りコマンドを実行し、再度辞書ファイルを作成すると詳細なエラーメッセージが表示されます。
　

　
エラーメッセージを見ながらエラーの原因になっている箇所を修正していくといいでしょう。
　
　

翻訳ファイルを反映させる方法・翻訳対象のメッセージを作成する方法

翻訳ファイルを反映させる方法

　
前項の作業を行い、日本語の翻訳ファイルを設置して画面をリロードすると日本語が表示されたと思います。
　
これは、日本語の端末を使っていますので、CakePHP3が言語を判断し、それに合う日本語の辞書ファイルを適用し、日本語を表示させたためです。
英語の端末でアクセスをすると、英語表記のままになります。
　
　
ですが、アクセスする端末によらず、強制的に日本語で表示したい、という場合もあるでしょう。
そういう場合の設定方法を解説します。
　
　

/config/app.php に指定をする方法

　
/config/app.phpに指定する方法があります。
　
app.phpの 40行目あたりから、CakePHP3の基本的な設定情報を記述する箇所があります。
　
この中にある「APP_DEFAULT_LOCALE」を「en_US」から「ja_JP」に変更します。
　

　
　
設定情報は、「app.php」ではなく、「/config/.env」を利用して設定している場合は、「.env」ファイルの中にある「APP_DEFAULT_LOCALE」を変更します。
　

コントローラーに指定をする方法

　
サイト全体ではなく、コントローラーやアクション単位で日本語化したい場合は下記のようにコントローラーに記述することでコントローラー単位で設定をすることもできます。
　
下記の 7行目、15行目の処理を追記します。
　

翻訳対象のメッセージを作成する方法

　
先に「__('*****')」の部分を翻訳ファイルに抽出します、と書きましたが、この翻訳対象とするメッセージの記述方法を紹介します。
　
　

「__('*****')」は完全一致で翻訳

　
翻訳対象のメッセージを設定する基本的な記述方法です。
　

　
上記の「__('*****')」形式で記述した場合は、翻訳ファイルにある「msgid “”」のテキストと完全一致した場合に対応する翻訳テキストが表示されます。
一致するものがない場合は、英語の表記がそのまま表示されます。
　
　

「__d('*****','*****')」は機能、プラグインごとに翻訳ファイルを分割

　
機能やプラグインごとに翻訳ファイルを分割したい場合は、下記のように「__d('*****','*****')」形式で記述します。
　

　
この場合、「/src/Locale/{言語フォルダ}/test_plugins.po」を翻訳ファイルとして読み込みます。
　
　

「__x('*****','*****')」は識別子で翻訳を振り分け

　
例えば、同じ「Submit」でも、登録画面では「登録実行」、更新画面では「更新実行」と翻訳を当てたい場合は、下記のように「__x('*****','*****')」形式で記述します。
　

動的な値をメッセージに含める場合

　
メッセージは固定の内容だけではなく、プログラムから取得する動的な値をメッセージに含めたい場合もあるでしょう。
そういう場合に動的にメッセージを入れる方法も用意されています。
　
まず、プログラムなどに記述するメッセージの方は、下記のように 1つ目のパラメータにプレースホルダー（{0}）付きのメッセージを記述します。
2つ目のパラメーターには実際に編集する文字列を配列で指定します。
　

　
上記の例では、「$place」「$food」の変数の値がプログラムで置き換える動的な値の部分です。
　
　
そして、翻訳ファイルのようには、下記のようにプレースホルダー付きのメッセージを翻訳するものと、動的に置き換えられるメッセージの翻訳したものとを記載していきます。
このようにしておくことで、動的に編集されるメッセージも日本語に翻訳されて画面に表示されます。
　

メッセージの中に「’（シングルクォート）」「”（ダブルクオート）」がある場合のエスケープ

　
例えば、「I don’t know.」という文章がある場合、「’（シングルクォート）」をどうしたらいいのか、と疑問に思う場合もあるかもしれません。
　
これらの場合は、PHPの基本的な処理と同様に「\」を使ってエスケープするか、「”（ダブルクオート）」で囲めば OKです。
　

　
「msgid」「msgstr」のパラメーターの指定は、「’」「”」のどちらでも問題ありませんので、メッセージの中に含まれる「’」「”」に合わせて変える、という方法でもいいのではないか、と思います。
　
プログラム規約で「’」に決まっている、という場合などはエスケープ処理をするといいでしょう。
　
　

ユーザ管理・ログイン認証プラグイン「CakeDC/Users」の日本語化

　
ユーザ管理・ログイン認証プラグインである「CakeDC/Users」の辞書ファイルは、プラグインとして別に持っています。
　
その CakeDC/Usersが持っている辞書ファイルを編集する方法については下記の記事を参考にしてください。
CakePHP3のプラグイン「CakeDC/Users」を日本語化・翻訳ファイルもダウンロード可
　
　

翻訳ファイル作成エディタ「Poedit」

　
CakePHP3 と WordPressとでは日本語化対応のための仕組みはやや異なりますが、WordPressには日本語の翻訳ファイルを作成するための便利なツール「Poedit」があります。
　
Poedit　オフィシャルサイト
https://poedit.net/
　
翻訳するときに日本語訳の例示を出してくれたり、何割の翻訳が終わっているかを表示してくれたりと、翻訳作業がはかどりやすくなるツールです。
CakePHP3では WordPressで使用する「.mo」ファイルの生成は必要ありませんが、CakePHP3の翻訳でも役に立ちますので、こういったツールを利用してみるのもいいでしょう。
　
下記の記事は WordPressの日本語化についての記事ですが、「Poedit」や「.pot」「.po」「.mo」ファイルについても書いていますので、あわせて参考にしてください。
PoeditでWordPressの日本語対応方法。英語プラグインの日本語翻訳ファイル作成
　
　

CakePHP3の関連記事