本地化

介绍

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

Laravel 的本地化功能提供了一种方便的方式来检索多种语言的字符串，使您能够轻松地在应用程序中支持多种语言。

Laravel 提供了两种管理翻译字符串的方式。首先，语言字符串可以存储在应用程序的 lang 目录中的文件中。在这个目录中，可能会有每种应用程序支持的语言的子目录。Laravel 使用这种方式来管理内置 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

配置Locale

您的应用程序的默认语言储存在 config/app.php 配置文件的 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);

    // ...
});

您可以配置一个“后备语言”，当活动语言不包含给定的翻译字符串时，将使用这种后备语言。像默认语言一样，后备语言也在 config/app.php 配置文件中配置：

'fallback_locale' => 'en',

确定当前的 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;

/**
 * 引导任何应用服务。
 *
 * @return void
 */
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还支持使用字符串的“默认”翻译作为键来定义翻译字符串。使用翻译字符串作为键的语言文件以 JSON 形式存储在 lang 目录中。例如，如果您的应用程序有西班牙语翻译，你应创建一个 lang/es.json 文件：

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

键/文件冲突

你不应该定义与其他翻译文件名冲突的翻译字符串键。例如，翻译 __('Action') 为“NL”语言，同时存在nl/action.php文件但不存在 nl.json 文件，将导致翻译器返回 nl/action.php 的全部内容。

提取翻译字符串

您可以使用 __ 辅助函数从语言文件中检索翻译字符串。如果您是使用"短键"定义您的翻译字符串，您应该使用"点"语法将包含键值和键值的文件传递给 __ 函数。例如，让我们从 lang/en/messages.php 语言文件中检索欢迎翻译字符串：

echo __('messages.welcome');

如果指定的翻译字符串不存在，__ 函数将返回翻译字符串的键。所以，使用上面的例子，__ 函数将返回 messages.welcome ，如果翻译字符串不存在。

如果您使用您的默认翻译字符串作为您的翻译键，您应该将您的字符串的默认翻译传递给 __ 函数；

echo __('我爱编程。');

同样的，如果翻译字符串不存在，__ 函数将返回给出的翻译字符串的键。

如果您正在使用 Blade 模板引擎，您可以使用 {{ }} echo 语法显示翻译字符串：

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

在翻译字符串中替换参数

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

'welcome' => '欢迎，:name',

在检索翻译字符串时替换占位符，您可以将替换项的数组作为 __ 函数的第二个参数传递：

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

如果您的占位符都是大写字母，或者只有第一个字母大写，翻译后的值将相应地大写：

'welcome' => '欢迎，:NAME', // 欢迎，DAYLE
'goodbye' => '再见，:Name', // 再见，Dayle

对象替换格式化

如果您尝试提供一个对象作为翻译占位符，对象的 __toString 方法将被调用。__toString 方法是 PHP 的内建的"魔术方法"之一。然而，有时候，您可能无法控制给定类的 __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' => '有一个苹果|有许多苹果',

当然，当使用翻译字符串作为键时，复数形式也是支持的：

{
    "有一个苹果|有许多苹果": "Hay una manzana|Hay muchas manzanas"
}

您甚至可以创建更复杂的复数形态规则，这些规则为多个值范围指定翻译字符串：

'apples' => '{0} 没有苹果|[1,19] 有一些苹果|[20,*] 有很多苹果',

在定义了有复数形式选项的翻译字符串后，您可以使用 trans_choice 函数根据给定的"数量"获取行。在这个例子中，由于计数大于一，所以返回的是翻译字符串的复数形式：

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} 没有苹果|{1} 有一个苹果|[2,*] 有 :count 个苹果',

覆盖包语言文件

有些包可能会附带自己的语言文件。与其改变包的核心文件来微调这些行，您可以通过在 lang/vendor/{package}/{locale} 目录中放置文件来覆盖它们。

所以，例如，如果您需要覆盖一个名为 skyrim/hearthfire 的包在 messages.php 中的英文翻译字符串，您应该在 lang/vendor/hearthfire/en/messages.php 中放置一个语言文件。在这个文件中，您应该只定义您希望覆盖的翻译字符串。您不覆盖的任何翻译字符串仍然会从包的原始语言文件中加载。