Appearance
本地化
介绍
NOTE
默认情况下,Laravel 应用程序框架不包括 lang
目录。如果你想自定义 Laravel 的语言文件,你可以通过 lang:publish
Artisan 命令发布它们。
Laravel 的本地化功能提供了一种便捷的方式来检索各种语言的字符串,使您可以轻松地在应用程序中支持多种语言。
Laravel 提供了两种管理翻译字符串的方法。首先,语言字符串可以存储在应用程序的 lang
目录中的文件中。在此目录中,应用程序支持的每种语言可能都有子目录。这是 Laravel 用来管理内置 Laravel 功能(例如验证错误消息)的翻译字符串的方法:
php
/lang
/en
messages.php
/es
messages.php
或者,可以在放置在 lang
目录中的 JSON 文件中定义翻译字符串。采用此方法时,您的应用程序支持的每种语言都将在此目录中具有相应的 JSON 文件。对于具有大量可翻译字符串的应用程序,建议使用此方法:
php
/lang
en.json
es.json
我们将在本文档中讨论管理翻译字符串的每种方法。
发布语言文件
默认情况下,Laravel 应用程序框架不包括 lang
目录。如果你想自定义 Laravel 的语言文件或创建自己的语言文件,你应该通过 lang:publish
Artisan 命令搭建 lang
目录的基架。lang:publish
命令将在您的应用程序中创建 lang
目录,并发布 Laravel 使用的默认语言文件集:
shell
php artisan lang:publish
配置 Locale
应用程序的默认语言存储在 config/app.php
配置文件的 locale
配置选项中,该选项通常使用 APP_LOCALE
环境变量进行设置。您可以自由修改此值以满足应用程序的需要。
您还可以配置“fallback language”,当默认语言不包含给定的翻译字符串时,将使用该语言。与默认语言一样,回退语言也在 config/app.php
配置文件中配置,其值通常使用 APP_FALLBACK_LOCALE
环境变量进行设置。
您可以在运行时使用 App
Facade 提供的 setLocale
方法修改单个 HTTP 请求的默认语言:
php
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
Facade 上使用 currentLocale
和 isLocale
方法来确定当前 locale 或检查 locale 是否为给定值:
php
use Illuminate\Support\Facades\App;
$locale = App::currentLocale();
if (App::isLocale('en')) {
// ...
}
复数语言
您可以指示 Elaravel 的“复数”,Eloquent 和框架的其他部分使用它来将单数字符串转换为复数字符串,使用英语以外的语言。这可以通过在应用程序的某个服务提供商的 boot
方法中调用 useLanguage
方法来实现。复数形式目前支持的语言为:法语
、挪威语-博克马尔
语、葡萄牙语
、西班牙语
和土耳其语
:
php
use Illuminate\Support\Pluralizer;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Pluralizer::useLanguage('spanish');
// ...
}
WARNING
如果你自定义复数形式的语言,你应该显式定义你的 Eloquent 模型的表名。
定义翻译字符串
使用快捷键
通常,翻译字符串存储在 lang
目录中的文件中。在此目录中,应用程序支持的每种语言都应该有一个子目录。这是 Laravel 用来管理内置 Laravel 功能(例如验证错误消息)的翻译字符串的方法:
php
/lang
/en
messages.php
/es
messages.php
所有语言文件都返回一个键控字符串数组。例如:
php
<?php
// lang/en/messages.php
return [
'welcome' => 'Welcome to our application!',
];
WARNING
对于因地区而异的语言,您应该根据 ISO 15897 命名语言目录。例如,“en_GB”应该用于英式英语,而不是“en-gb”。
使用翻译字符串作为键
对于具有大量可翻译字符串的应用程序,在视图中引用键时,使用 “short key” 定义每个字符串可能会变得混乱,并且不断为应用程序支持的每个翻译字符串创建键是很麻烦的。
因此,Laravel 还支持使用字符串的 “default” 翻译作为键来定义翻译字符串。使用翻译字符串作为键的语言文件将作为 JSON 文件存储在 lang
目录中。例如,如果您的应用程序具有西班牙语翻译,则应创建一个 lang/es.json
文件:
json
{
"I love programming.": "Me encanta programar."
}
密钥/文件冲突
您不应定义与其他翻译文件名冲突的翻译字符串键。例如,在 nl/action.php
文件存在但 nl.json
文件不存在的情况下翻译 “NL” 语言环境的 __('Action')
将导致翻译器返回 nl/action.php
的全部内容。
检索翻译字符串
您可以使用 __
helper 函数从语言文件中检索翻译字符串。如果您使用 “short keys” 来定义翻译字符串,则应使用 “dot” 语法将包含密钥和密钥本身的文件传递给 __
函数。例如,让我们从 lang/en/messages.php
语言文件中检索欢迎
翻译字符串:
php
echo __('messages.welcome');
如果指定的翻译字符串不存在,则 __
函数将返回翻译字符串键。因此,使用上面的示例,如果翻译字符串不存在,则 __
函数将返回 messages.welcome
。
如果您使用默认翻译字符串作为翻译键,则应将字符串的默认翻译传递给 __
函数;
php
echo __('I love programming.');
同样,如果翻译字符串不存在,则 __
函数将返回给定的翻译字符串键。
如果您使用的是 Blade 模板引擎,则可以使用 echo 语法来显示翻译字符串:
{{ __('messages.welcome') }}
替换翻译字符串中的参数
如果您愿意,您可以在翻译字符串中定义占位符。所有占位符都以 :
为前缀。例如,您可以定义带有占位符名称的欢迎消息:
php
'welcome' => 'Welcome, :name',
要在检索翻译字符串时替换占位符,您可以将替换数组作为第二个参数传递给 __
函数:
php
echo __('messages.welcome', ['name' => 'dayle']);
如果您的占位符包含所有大写字母,或者只有其第一个字母大写,则翻译后的值将相应地大写:
php
'welcome' => 'Welcome, :NAME', // Welcome, DAYLE
'goodbye' => 'Goodbye, :Name', // Goodbye, Dayle
对象替换格式
如果您尝试将对象作为翻译占位符提供,则将调用该对象的 __toString
方法。__toString
方法是 PHP 内置的 “魔术方法” 之一。但是,有时您可能无法控制给定类的 __toString
方法,例如,当您与之交互的类属于第三方库时。
在这些情况下,Laravel 允许您为该特定类型的对象注册自定义格式处理程序。为此,您应该调用翻译器的 stringable
方法。stringable
方法接受一个闭包,该闭包应该对它负责格式化的对象类型进行类型提示。通常,应在应用程序的 AppServiceProvider
类的 boot
方法中调用可字符串
化方法:
php
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 可以帮助您根据您定义的复数规则以不同的方式翻译字符串。使用 |
字符,您可以区分字符串的单复数形式:
php
'apples' => 'There is one apple|There are many apples',
当然,当使用翻译字符串作为键时,也支持复数形式:
json
{
"There is one apple|There are many apples": "Hay una manzana|Hay muchas manzanas"
}
您甚至可以创建更复杂的复数规则,为多个值范围指定翻译字符串:
php
'apples' => '{0} There are none|[1,19] There are some|[20,*] There are many',
定义具有复数选项的翻译字符串后,您可以使用 trans_choice
函数来检索给定 “count” 的行。在此示例中,由于 count 大于 1,因此返回翻译字符串的复数形式:
php
echo trans_choice('messages.apples', 10);
您还可以在复数字符串中定义 placeholder 属性。可以通过将数组作为第三个参数传递给 trans_choice
函数来替换这些占位符:
php
'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',
echo trans_choice('time.minutes_ago', 5, ['value' => 5]);
如果你想显示传递给 trans_choice
函数的整数值,你可以使用内置的 :count
占位符:
php
'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
。在此文件中,您应该只定义要覆盖的翻译字符串。您未覆盖的任何翻译字符串仍将从包的原始语言文件中加载。