ローカライゼーション

はじめに
翻訳文字列の定義
- ショートキーの使用
- 翻訳文字列をキーとして使用する
翻訳文字列の取得
- 翻訳文字列のパラメータの置換
- 複数形
パッケージ言語ファイルのオーバーライド

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

php artisan lang:publish

ロケールの設定

アプリケーションのデフォルト言語は、config/app.php設定ファイルのlocale設定オプションに保存され、通常はAPP_LOCALE環境変数を使用して設定されます。この値は、アプリケーションのニーズに合わせて自由に修正できます。

また、「フォールバック言語」を設定することもできます。これは、デフォルト言語に特定の翻訳文字列が含まれていない場合に使用されます。デフォルト言語と同様に、フォールバック言語もconfig/app.php設定ファイルで設定され、通常はAPP_FALLBACK_LOCALE環境変数を使用して設定されます。

Appファサードによって提供されるsetLocaleメソッドを使用して、実行時に単一のHTTPリクエストのデフォルト言語を変更できます。

use Illuminate\Support\Facades\App;
 
Route::get('/greeting/{locale}', function (string $locale) {
    if (! in_array($locale, ['en', 'es', 'fr'])) {
        abort(400);
    }
 
    App::setLocale($locale);
 
    // ...
});

現在のロケールの決定

AppファサードのcurrentLocaleメソッドとisLocaleメソッドを使用して、現在のロケールを決定したり、ロケールが特定の値であるかどうかを確認したりできます。

use Illuminate\Support\Facades\App;
 
$locale = App::currentLocale();
 
if (App::isLocale('en')) {
    // ...
}

複数形言語

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

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

複数形化ツールの言語をカスタマイズする場合は、Eloquentモデルのテーブル名を明示的に定義する必要があります。

翻訳文字列の定義

ショートキーの使用

通常、翻訳文字列はlangディレクトリ内のファイルに格納されます。このディレクトリ内には、アプリケーションでサポートされている各言語のサブディレクトリが必要です。これは、Laravelがバリデーションエラーメッセージなどの組み込みLaravel機能の翻訳文字列を管理するために使用する方法です。

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

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

<?php
 
// lang/en/messages.php
 
return [
    'welcome' => 'Welcome to our application!',
];

地域によって異なる言語の場合は、言語ディレクトリをISO 15897に従って命名する必要があります。たとえば、「en-gb」ではなく、イギリス英語には「en_GB」を使用する必要があります。

翻訳文字列をキーとして使用する

翻訳可能な文字列が多いアプリケーションでは、すべての文字列を「短いキー」で定義すると、ビューでキーを参照するときに混乱を招き、アプリケーションでサポートされているすべての翻訳文字列に対してキーを継続的に作成するのは面倒です。

このため、Laravelは、文字列の「デフォルト」翻訳をキーとして使用して翻訳文字列を定義することもサポートしています。翻訳文字列をキーとして使用する言語ファイルは、langディレクトリにJSONファイルとして格納されます。たとえば、アプリケーションにスペイン語の翻訳がある場合は、lang/es.jsonファイルを作成する必要があります。

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

キー/ファイル競合

他の翻訳ファイル名と競合する翻訳文字列キーを定義しないでください。たとえば、nl/action.phpファイルが存在するのにnl.jsonファイルが存在しない状態で、「NL」ロケールに対して__('Action')を翻訳すると、トランスレータは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の組み込み「マジックメソッド」の1つです。ただし、サードパーティのライブラリに属するクラスなど、操作しているクラスの__toStringメソッドを制御できない場合があります。

このような場合、Laravelでは、その特定の型のオブジェクトに対してカスタムフォーマットハンドラーを登録できます。これを実現するには、トランスレータの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に言語ファイルを配置する必要があります。このファイル内では、オーバーライドしたい翻訳文字列のみを定義する必要があります。オーバーライドしない翻訳文字列は、パッケージの元の言語ファイルからロードされます。