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

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

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

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

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

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

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

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

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

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

　
最後まで実行すると、
「/var/www/html/example.com/resources/locales/」
に、辞書ファイル
「cake.pot」
「default.pot」
などが生成されていますので、それを確認します。
　
「cake.pot」は CakePHPのシステム自体で使用しているメッセージをもとにした辞書ファイルで、
「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/resources/locales/default.pot」ファイルが存在する場合は、下記の確認が追加されます。
上書きする場合は「y」を選択します。
もし、すでに日本語化したファイルがある場合は、「default.pot」のファイル名を変更するなどして対応してください。
　

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

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

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

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

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

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

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

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

　
前項で作成した「ja」フォルダの中に、作成された「default.pot」を「default.po」にファイル名を変更して設置します。
　
※拡張子を「.pot」から「.po」に変更します。「default」のファイル名には意味がありますので、ファイル名自体は変更しないようにしましょう。
※プラグインなどをインストールしている場合などは、「default.pot」以外にも「cake.pot」「users.pot」などの複数の「xxxx.pot」ファイルが生成される場合があります。それらすべてを「ja」フォルダの中に設置します。
　
これで設置完了です。
　
　

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

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

　
　

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

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

翻訳を記述するファイルは「default.po」の方

　
「i18n」コマンドで「default.pot」を生成し、それをもとに「default.po」ファイルを生成しますが、英語のメッセージの対訳を入力するファイル（編集するファイル）は「default.po」になります。
　
「default.pot」をコピーして「default.po」を作成したのち、「default.po」を開いて対訳を付けていきます。
　
プログラムの追加開発などを行った場合は、改めて「i18n」コマンドを実行して「default.pot」ファイルを生成しなおしますが、この際、「default.pot」ファイルは上書きされてしまいます。
対訳を付けていても消えてしまいます。
　
また、この記事の一番最後に紹介していますが、翻訳ファイル作成エディタ「Poedit」を使うと、「default.po」に「default.pot」の追加されたメッセージだけを取り込むこともできますので、「Poedit」などのエディタなどを活用して、翻訳するといいかと思います。
　
　
ちなみに、「default.pot」は本番環境では必要ないファイルですので、リリース対象ファイルから外すといった対応もあってもいいのかと思います。
　
　

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

　
コマンド「bin/cake i18n」を実行して、テンプレートを作成する時にエラーが発生すると、下記のようなエラーメッセージを見ることがあります。
　
7 marker error(s) detected.
=> Use the --marker-error option to display errors.
　
これは、辞書ファイル「default.pot」を生成する際に不具合がありました（上記の例では 7ヶ所）というメッセージとなります。
　
そのため、改めて、下記のオプションを付与して「default.pot」を生成するコマンドを実行すると、どのファイルの何行目の処理でエラーが発生したのか、詳細情報を表示してくれます。（すでに生成した「default.pot」のエラーメッセージを表示させるのではなく、改めて再作成する際に発生するエラーメッセージを表示する、と言う方法になります。）
　

　
あとは、表示されるエラーメッセージを見ながらエラーの原因を修正するか、無視するか、の対応をするといいでしょう。
　
プログラムの処理が絡んでいる箇所は、間違っていないけど、「i18n」コマンドが処理できないだけ、という場合もありますので、場合によっては無視する対応も出てくるかと思います。
　
　

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

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

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

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

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

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

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

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

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

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

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

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

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

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

　
例えば、「test」という単語があるとします。
「default.po」の方では「テスト」と翻訳を当てたいが、「test_plugins.po」の方では「試験」と翻訳を当てたい場合があるとします。
　
そんな時は、プラグイン名（翻訳ファイル名）を指定することで、当てる翻訳を指定することができます。
　
具体的には、下記のように「__d('*****','*****')」形式で記述します。
　

　
この場合、「/resources/locales/{言語フォルダ}/test_plugins.po」を翻訳ファイルとして読み込みます。
（「test_plugins」を指定しない場合は、「default」の方を使用します。）
　
　

「__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」

　
「default.po」の英語をもとに日本語の翻訳をしていく作業には「Poedit」という便利なツールがあります。
　
Poedit　オフィシャルサイト
https://poedit.net/
　

• 「事前翻訳」という機能で「DeepL」「Google Translate」「Microsoft Translator」を使って一括翻訳をしてくれる機能
• 「.pot」ファイルに追加されたメッセージを、翻訳編集中の「.po」ファイルにマージする機能
• 翻訳するときに日本語訳の例を出してくれる機能
• メッセージのうち何件中何件翻訳済み、などを表示してくれる機能

などなど、翻訳をする際にお役立ちの機能がいろいろ入っています。
　
有償版もありますが、おおよその機能は無償版で利用することができます。
　
もともとは WordPressを多言語化するためのツールだったようで、WordPressで使用する「.mo」ファイル（CakePHP4では使用しないファイル）を生成する機能などもありますが、CakePHP4の翻訳でも役に立ちますので、こういったツールを利用してみるのもいいかと思います。
　
下記の記事は WordPressの日本語化についての記事ですが、「Poedit」や「.pot」「.po」「.mo」ファイルについても書いていますので、あわせて参考にしてください。
PoeditでWordPressの日本語対応方法。英語プラグインの日本語翻訳ファイル作成
　
　

CakePHP4の関連記事