【Laravel】多言語化で言語毎の翻訳文字列を取得する__()とtrans()とtrans_choice()




Laravel(検証はLaravel5.7)で多言語化する際、言語毎に翻訳設定ファイルを用意し、翻訳キーと翻訳文字列を定義していきます。
ここで定義した翻訳文字列は__()やtrans()などのヘルパー関数を利用して取得することができますが、このヘルパー関数について整理します。
なお、動作を確認する際、以下の処理を参考にしました。

vendor/laravel/framework/src/Illuminate/Foundation/helpers.php
vendor/laravel/framework/src/Illuminate/Translation/Translator.php

動作確認前提条件

説明で使用するコードについては以下を前提条件とします。

アプリケーションのロケール設定

// config/app.php
'locale' => 'en',
'fallback_locale' => 'en',

翻訳設定

// resources/lang/en.json
{
    "I have a pen.": "[json][en]I have a pen."
}
// resources/lang/ja.json
{
    "I have a pen.": "[json][ja]私はペンを持っている。"
}
// resources/lang/en/helper.php
return [
    'I have a pen.' => '[php][en]I have a pen.',
    'I have a book.' => '[php][en]I have a book.',
];
// resources/lang/ja/helper.php
return [
    'I have a pen.' => '[php][ja]私はペンを持っている。',
];

翻訳設定ファイル

翻訳設定ファイルは2種類あります。

(1)resources/lang/{言語}/{識別子}.phpで設定

言語ディレクトリ配下に任意のファイル名を作成し、その中に翻訳キーと翻訳文字列を定義します。
{言語}は2桁の言語コード(ISO 639-1)を設定します。
例えばファイル名をhelper.phpとする場合、英語ならresources/lang/en/helper.php、日本語ならresources/lang/ja/helper.phpとなります。
本記事内に限り、JSONファイルと記載します。

(2)resources/{言語}.jsonで設定

resources/lang/配下に{言語}.jsonという名前でファイルを作成し、翻訳キーと翻訳文字列を定義します。
{言語}は2桁の言語コード(ISO 639-1)を設定します。
例えば英語ならresources/lang/en.json、日本語ならresources/lang/ja.jsonとなります。
本記事内に限り、PHPファイルと記載します。

__()

パラメータ

第1引数:[必須]翻訳キー
第2引数:翻訳文字列中のプレースホルダーの置換する値(配列)
第3引数:ロケール

使い方

基本的な使い方

翻訳キーを第1引数に指定すると、app.phpで設定したlocaleに対応する翻訳キーを(1)JSONファイル、(2)PHPファイルの順番で検索し、先に見つかった翻訳文字列を返します。
見つからなかった場合、app.phpで設定したfallback_localeの翻訳キーを検索し、見つかった場合は翻訳文字列を返します。
見つからなかった場合、検索キーを返します。

// JSONファイルに翻訳文字列を以下で定義した場合
'I have a pen.' => 'I have a pen.',

// 呼び出し
echo __('I have a pen.');
// I have a pen.

翻訳文字列にプレースホルダーを利用

翻訳文字列にはプレースホルダーを設定することができ、設定した場合、第2引数に置換するキーと値を配列で定義できます。
翻訳文字列のプレースホルダーは「:キー」というように先頭コロンで定義します。
JSONファイル、PHPファイルどちらでも設定できます。

// JSONファイルに翻訳文字列を以下で定義した場合
'I have a xxxx.' => 'I have a :xxxx.',

// 呼び出し
echo __('I have a xxxx.', ['xxxx' => 'cup']);
// I have a cup.

ロケールを指定

第3引数には取得したいロケールを指定できます。
アプリケーションで設定したロケールとは別のロケールの翻訳テキストを取得したい場合に利用します。
例えばアプリケーションの設定はenになっているが、特定箇所のみjaの翻訳文字列をしゅとくしたい場合などに利用します。

// JSONファイルに翻訳文字列を以下で定義した場合
'I have a pen.' => '私はペンを持っている。',

// 呼び出し
echo __('I have a xxxx.', [], 'ja');
// 私はペンを持っている。

trans()

パラメータ

__()と同じです。

第1引数:[必須]翻訳キー
第2引数:翻訳文字列中のプレースホルダーの置換する値(配列)
第3引数:ロケール

使い方

翻訳キー検索でJSONファイルを検索しないこと以外は__()と同じです。

trans_choice()

パラメータ

第1引数:[必須]翻訳キー
第2引数:[必須]翻訳番号
第4引数:翻訳文字列中のプレースホルダーの置換する値(配列)
第4引数:ロケール

使い方

trans()とほぼ同じですが、ひとつの翻訳キーの中に複数の翻訳パターンを設定することができることが大きな違いです。
なお、trans()と同じでJSONファイルには対応していません。

(1)パイプ記号で2つに区切る。
このときは第2引数が0の時と1の時を設定します。
3つ以上定義しても最初の二つ以外は無視されます。

// PHPファイルに翻訳文字列を以下で定義した場合
'text1' => 'AAA|BBB',

// 呼び出し
echo trans_choice('helper.text1', 0));
// AAA
echo trans_choice('helper.text1', 1));
// BBB
echo trans_choice('helper.text1', 2));
// AAA ←条件が一致しない場合は翻訳番号0が表示される

(2)パイプ記号で2つに区切り、かつ、翻訳番号を指定する。
この場合、3つ以上の翻訳文字列を定義できます。
翻訳番号の定義は1つだけの場合は「[1]」(翻訳番号:1)、複数の場合は「{2,5}」(翻訳番号:2〜5)のように定義します。

// PHPファイルに翻訳文字列を以下で定義した場合
'number_text' => '[0]zero|[1]one|{2,99}over two',

// 呼び出し
echo trans_choice('helper.number_text', 0));
// zero
echo trans_choice('helper.number_text', 1));
// one
echo trans_choice('helper.number_text', 2));
// over two ← 2〜99の場合
echo trans_choice('helper.number_text', 100));
// one ← 条件が一致しない場合はすべて翻訳番号1が表示される