介绍

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

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方法来实现。复数化器当前支持的语言有：法语、挪威语（波克默尔语）、葡萄牙语、西班牙语和土耳其语：

use Illuminate\Support\Pluralizer;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Pluralizer::useLanguage('西班牙语');

    //...
}

[!警告]
如果您自定义复数化器的语言，您应该明确定义您的 Eloquent 模型的表名。

定义翻译字符串

使用短键

通常，翻译字符串存储在lang目录中的文件中。在该目录中，对于您的应用程序支持的每种语言，都应该有一个子目录。这是 Laravel 用于管理内置 Laravel 功能（如验证错误消息）的翻译字符串的方法：

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

所有语言文件都返回一个带键的字符串数组。例如：

<?php

// lang/en/messages.php

return [
    'welcome' => '欢迎来到我们的应用程序！',
];

[!警告]
对于因地区而异的语言，您应该根据 ISO 15897 命名语言目录。例如，“en_GB”应该用于英式英语，而不是“en-gb”。

使用翻译字符串作为键

对于具有大量可翻译字符串的应用程序，在视图中引用键时，使用“短键”定义每个字符串可能会变得混乱，并且为应用程序支持的每个翻译字符串不断发明键是很麻烦的。

因此，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 模板引擎，您可以使用{{ }}回显语法来显示翻译字符串：

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

在翻译字符串中替换参数

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

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

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

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

如果您的占位符全部为大写字母，或者只有首字母大写，那么翻译后的值将相应地大写：

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

对象替换格式化

如果您尝试将对象作为翻译占位符提供，将调用该对象的 __toString 方法。__toString (opens in a new tab) 方法是 PHP 内置的“魔术方法”之一。然而，有时您可能无法控制给定类的 __toString 方法，例如当您正在与之交互的类属于第三方库时。

在这些情况下，Laravel 允许您为该特定类型的对象注册一个自定义格式化处理程序。要实现此目的，您应该调用翻译器的 stringable 方法。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 放置一个语言文件。在这个文件中，您应该只定义您想要覆盖的翻译字符串。任何您未覆盖的翻译字符串仍将从包的原始语言文件中加载。