ローカリゼーション

• はじめに
  • 言語ファイルの公開
  • ロケールの設定
  • 複数形の言語設定
• 翻訳文字列の定義
  • ショートキーの使用
  • 翻訳文字列をキーとして使う
• 翻訳文字列の取得
  • 翻訳文字列内のパラメータ置換
  • 複数形の処理
• パッケージの言語ファイルの上書き

#はじめに

Laravelのローカリゼーション機能は、さまざまな言語の文字列を簡単に取得できる仕組みを提供し、アプリケーションで複数言語を簡単にサポートできます。

Laravelは翻訳文字列を管理する方法を2つ提供します。まず、言語文字列はアプリケーションの lang ディレクトリ内のファイルに保存できます。このディレクトリ内には、サポートする各言語ごとにサブディレクトリが存在します。この方法は、バリデーションエラーメッセージなどLaravel組み込み機能の翻訳文字列管理に使われています：

/lang
    /en
        messages.php
    /es
        messages.php

または、翻訳文字列をJSONファイルとして lang ディレクトリに配置する方法もあります。この場合、アプリケーションがサポートする各言語ごとに対応するJSONファイルを用意します。大量の翻訳文字列があるアプリケーションにはこちらの方法が推奨されます：

/lang
    en.json
    es.json

このドキュメントでは、翻訳文字列の管理方法それぞれについて説明します。

#言語ファイルの公開

デフォルトでは、Laravelのアプリケーションスケルトンに lang ディレクトリは含まれていません。Laravelの言語ファイルをカスタマイズしたり独自に作成したい場合は、lang:publish Artisanコマンドで lang ディレクトリをスキャフォールドしてください。lang:publish コマンドはアプリケーションに lang ディレクトリを作成し、Laravelが使用するデフォルトの言語ファイルセットを公開します：

php artisan lang:publish

#ロケールの設定

アプリケーションのデフォルト言語は config/app.php 設定ファイルの locale オプションに保存されています。必要に応じてこの値を変更できます。

単一のHTTPリクエストの実行時に、App ファサードの setLocale メソッドを使ってデフォルト言語を変更できます：

use Illuminate\Support\Facades\App;

Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'es', 'fr'])) {
        abort(400);
    }

    App::setLocale($locale);

    // ...
});

アクティブな言語に翻訳文字列が存在しない場合に使用される「フォールバック言語」も設定できます。フォールバック言語も config/app.php 設定ファイルで指定します：

'fallback_locale' => 'en',

#現在のロケールの判定

App ファサードの currentLocale と isLocale メソッドを使って、現在のロケールを取得したり特定の値かどうかを判定できます：

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

if (App::isLocale('en')) {
    // ...
}

#複数形の言語設定

Eloquentやフレームワークの他の部分で単数形を複数形に変換するために使われるLaravelの「pluralizer」に対して、英語以外の言語を使うよう指示できます。これはアプリケーションのサービスプロバイダーの boot メソッド内で useLanguage メソッドを呼び出すことで実現します。現在サポートされている言語は french、norwegian-bokmal、portuguese、spanish、turkish です：

use Illuminate\Support\Pluralizer;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');

    // ...
}

#翻訳文字列の定義

#ショートキーの使用

通常、翻訳文字列は lang ディレクトリ内のファイルに保存します。このディレクトリ内には、サポートする各言語ごとにサブディレクトリを用意します。この方法は、バリデーションエラーメッセージなどLaravel組み込み機能の翻訳文字列管理に使われています：

/lang
    /en
        messages.php
    /es
        messages.php

すべての言語ファイルはキー付き文字列の配列を返します。例えば：

<?php

// lang/en/messages.php

return [
    'welcome' => 'Welcome to our application!',
];

#翻訳文字列をキーとして使う

大量の翻訳文字列があるアプリケーションでは、すべての文字列にショートキーを定義すると、ビューでキーを参照する際に混乱しやすく、毎回キーを考えるのも手間です。

そのため、Laravelは翻訳文字列の「デフォルト翻訳」をキーとして使う方法もサポートしています。翻訳文字列をキーとして使う言語ファイルは lang ディレクトリのJSONファイルとして保存します。例えば、アプリケーションにスペイン語の翻訳がある場合は lang/es.json ファイルを作成します：

{
    "I love programming.": "Me encanta programar."
}

#キーとファイルの競合

翻訳文字列のキーが他の翻訳ファイル名と競合しないようにしてください。例えば、"NL" ロケールで __('Action') を翻訳しようとして nl/action.php ファイルが存在し、nl.json ファイルが存在しない場合、翻訳は nl/action.php の内容全体を返してしまいます。

#翻訳文字列の取得

__ ヘルパー関数を使って言語ファイルから翻訳文字列を取得できます。ショートキーを使っている場合は、キーを含むファイル名とキーをドット記法で __ 関数に渡します。例えば、lang/en/messages.php の welcome 翻訳文字列を取得するには：

echo __('messages.welcome');

指定した翻訳文字列が存在しない場合、__ 関数は翻訳文字列のキーを返します。したがって、上の例のように翻訳文字列が存在しない場合、__ 関数は messages.welcome を返します。

翻訳文字列をキーとして使う場合は、文字列のデフォルト翻訳を __ 関数に渡してください；

echo __('I love programming.');

同様に、翻訳文字列が存在しなければ、__ 関数は渡された翻訳キーを返します。

Bladeテンプレートエンジンを使っている場合は、{{ }} エコー構文で翻訳文字列を表示できます：

{{ __('messages.welcome') }}

#翻訳文字列内のパラメータ置換

翻訳文字列内にプレースホルダーを定義できます。すべてのプレースホルダーは : で始まります。例えば、名前のプレースホルダーを含む歓迎メッセージを定義できます：

'welcome' => 'Welcome, :name',

翻訳文字列を取得する際に、__ 関数の第2引数に置換用の配列を渡してプレースホルダーを置換できます：

echo __('messages.welcome', ['name' => 'dayle']);

プレースホルダーがすべて大文字、または先頭だけ大文字の場合、翻訳された値もそれに応じて大文字化されます：

'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle

#オブジェクト置換のフォーマット

オブジェクトを翻訳プレースホルダとして渡そうとすると、そのオブジェクトの__toStringメソッドが呼び出されます。__toStringメソッドは、PHPに組み込まれた「マジックメソッド」の一つです。ただし、やりとりしているクラスがサードパーティ製ライブラリに属している場合など、特定のクラスの__toStringメソッドを制御できないことがあります。

このような場合、Laravelでは特定の型のオブジェクトに対してカスタムのフォーマットハンドラを登録できます。これを行うには、translatorのstringableメソッドを呼び出します。stringableメソッドはクロージャを受け取り、そのクロージャはフォーマットを担当するオブジェクトの型を型ヒントする必要があります。通常、stringableメソッドはアプリケーションのAppServiceProviderクラスのbootメソッド内で呼び出します:

use Illuminate\Support\Facades\Lang;
use Money\Money;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Lang::stringable(function (Money $money) {
        return $money->formatTo('en_GB');
    });
}

#複数形の処理

複数形の処理は複雑で、言語ごとにさまざまなルールがありますが、Laravelは定義した複数形ルールに基づいて文字列を切り替えられます。| 文字を使って単数形と複数形を区別します：

'apples' => 'There is one apple|There are many apples',

もちろん、翻訳文字列をキーとして使う場合も複数形に対応しています：

{
    "There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
}

複数の値の範囲に応じた複雑な複数形ルールも作成できます：

'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',

複数形オプションを含む翻訳文字列を定義したら、trans_choice 関数で指定した「数」に対応する行を取得できます。この例では数が1より大きいため、複数形の翻訳文字列が返されます：

echo trans_choice('messages.apples', 10);

複数形文字列内にプレースホルダーを定義し、trans_choice 関数の第3引数に配列を渡して置換できます：

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',

echo trans_choice('time.minutes_ago', 5, ['value' => 5]);

trans_choice 関数に渡した整数値を表示したい場合は、組み込みの :count プレースホルダーを使えます：

'apples' => '{0} There are none|{1} There is one|[2,*] There are :count',

#パッケージの言語ファイルの上書き

一部のパッケージは独自の言語ファイルを含みます。パッケージのコアファイルを直接変更する代わりに、lang/vendor/{package}/{locale} ディレクトリにファイルを置いて上書きできます。

例えば、skyrim/hearthfire というパッケージの英語翻訳 messages.php を上書きしたい場合は、lang/vendor/hearthfire/en/messages.php に言語ファイルを置きます。このファイルには上書きしたい翻訳文字列だけを定義してください。上書きしない翻訳文字列はパッケージの元の言語ファイルから読み込まれます。