本地化

简介

Laravel 的本地化功能提供了一种便捷的方式来获取多种语言的字符串，让你可以在应用中轻松支持多语言。

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

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

第二种是将翻译字符串定义在放置于 lang 目录下的 JSON 文件中。采用这种方式时，应用支持的每种语言在该目录下都有对应的 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 配置选项中，通常通过 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')) {
    // ...
}

复数化语言

你可以指示 Laravel 的「复数化器」（Eloquent 和框架其他部分用它将单数字符串转换为复数字符串）使用英语以外的语言。这可以通过在应用某个服务提供者的 boot() 方法中调用 useLanguage() 方法来实现。复数化器目前支持的语言有：french、norwegian-bokmal、portuguese、spanish 和 turkish：

use Illuminate\Support\Pluralizer;

/**
 * 引导应用服务。
 */
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 还支持使用字符串的「默认」翻译作为键来定义翻译字符串。使用翻译字符串作为键的语言文件以 JSON 格式存储在 lang 目录中。例如，如果你的应用有西班牙语翻译，应创建 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 模板引擎，可以使用 {{ }} echo 语法来显示翻译字符串：

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

替换翻译字符串中的参数

可以在翻译字符串中定义占位符。所有占位符都以 : 前缀。例如，定义带名称占位符的欢迎消息：

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

获取翻译字符串时，可以将替换数组作为第二个参数传给 __ 函数来替换占位符：

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

如果占位符全大写或仅首字母大写，翻译值也会相应地大写：

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

对象替换格式化

如果尝试将对象作为翻译占位符，对象的 __toString 方法会被调用。__toString 方法是 PHP 内置的「魔术方法」之一。但有时你可能无法控制给定类的 __toString 方法，例如当你交互的类属于第三方库时。

在这些情况下，Laravel 允许你为特定类型的对象注册自定义格式化处理器。为此，应调用翻译器的 stringable() 方法。该方法接受一个闭包，闭包应类型提示它负责格式化的对象类型。通常，stringable() 方法应在应用 AppServiceProvider 类的 boot() 方法中调用：

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

/**
 * 引导应用服务。
 */
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() 函数来替换这些占位符：

'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。在此文件中，只需定义要覆盖的翻译字符串。未覆盖的翻译字符串仍会从包的原始语言文件中加载。