Laravel 中文文档

主题

全部文档

本地化 ​

简介 ​

INFO

默认情况下，Laravel 应用骨架不包含 lang 目录。若要自定义 Laravel 的语言文件，可通过 lang:publish Artisan 命令发布它们。

Laravel 的本地化功能提供了便捷的方式，按不同语言获取字符串，从而轻松在应用中支持多语言。

Laravel 提供两种管理翻译字符串的方式。第一种是将语言字符串存放在应用的 lang 目录中的文件里。该目录下可为应用支持的每种语言建立子目录。Laravel 自身也用这种方式管理内置功能（如验证错误消息）的翻译字符串：

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

或者，也可将翻译字符串定义在放置于 lang 目录中的 JSON 文件里。采用这种方式时，应用支持的每种语言在该目录下对应一个 JSON 文件。对于有大量可翻译字符串的应用，推荐使用此方式：

text
/lang
    en.json
    es.json

本文将分别介绍这两种管理翻译字符串的方式。

发布语言文件 ​

默认情况下，Laravel 应用骨架不包含 lang 目录。若要自定义 Laravel 的语言文件或创建自己的语言文件，应通过 lang:publish Artisan 命令搭建 lang 目录。该命令会在应用中创建 lang 目录，并发布 Laravel 使用的默认语言文件集：

shell
php artisan lang:publish

配置语言区域 ​

应用的默认语言保存在 config/app.php 配置文件的 locale 选项中，通常通过 APP_LOCALE 环境变量设置。你可按应用需求自由修改该值。

你还可以配置「回退语言」：当默认语言中不存在某个翻译字符串时将使用它。与默认语言一样，回退语言也在 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 方法判断当前语言区域，或检查是否为某个给定值：

php
use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

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

复数化语言 ​

你可以指示 Laravel 的「复数化」组件（Eloquent 及框架其他部分用它将单数字符串转为复数）使用英语以外的语言。在某个服务提供者的 boot 方法中调用 useLanguage 即可。复数化组件当前支持的语言为：french、norwegian-bokmal、portuguese、spanish 和 turkish：

php
use Illuminate\Support\Pluralizer;

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

    // ...
}

WARNING

若自定义了复数化语言，应显式定义 Eloquent 模型的表名。

定义翻译字符串 ​

使用短键 ​

通常，翻译字符串存放在 lang 目录下的文件中。该目录下应为应用支持的每种语言建立一个子目录。Laravel 自身也用这种方式管理内置功能（如验证错误消息）的翻译字符串：

text
/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。

使用翻译字符串作为键 ​

对于有大量可翻译字符串的应用，为每条字符串定义「短键」会在视图中引用时变得混乱，而且持续为每条翻译发明键名也很繁琐。

因此，Laravel 也支持以字符串的「默认」译文作为键来定义翻译。使用翻译字符串作为键的语言文件以 JSON 形式存放在 lang 目录中。例如，若应用有西班牙语翻译，应创建 lang/es.json 文件：

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

键 / 文件冲突 ​

不应定义与其他翻译文件名冲突的翻译字符串键。例如，为「NL」语言区域翻译 __('Action') 时，若存在 nl/action.php 却不存在 nl.json，翻译器会返回整个 nl/action.php 的内容。

获取翻译字符串 ​

可使用 __ 辅助函数从语言文件中获取翻译字符串。若使用「短键」定义翻译，应使用「点」语法，将包含该键的文件与键本身传给 __ 函数。例如，从 lang/en/messages.php 语言文件获取 welcome 翻译字符串：

php
echo __('messages.welcome');

若指定的翻译字符串不存在，__ 函数会返回该翻译键。因此，在上面的例子中，若不存在对应翻译，__ 会返回 messages.welcome。

若使用默认翻译字符串作为翻译键，应将字符串的默认译文传给 __ 函数：

php
echo __('I love programming.');

同样，若翻译字符串不存在，__ 函数会返回传入的翻译键。

若使用 Blade 模板引擎，可使用 &#123;&#123; &#125;&#125; 输出语法显示翻译字符串：

blade
{{ __('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 方法。该方法接受一个闭包，闭包应对所负责格式化的对象类型进行类型提示。通常应在应用的 AppServiceProvider 类的 boot 方法中调用 stringable：

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);

也可在复数化字符串中定义占位符属性。将这些占位符作为第三个参数传给 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。在该文件中只需定义希望覆盖的翻译字符串；未覆盖的仍会从包的原始语言文件加载。