本地化

引言

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

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

Laravel 提供了两种管理翻译字符串的方式。首先，语言字符串可以存储在应用程序的 lang 目录下的文件中。在该目录中，可以为每种应用程序支持的语言创建子目录。这是 Laravel 用于管理内置功能（如验证错误消息）翻译字符串的方式：

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

另外，翻译字符串也可以定义在 JSON 文件中，这些文件放在 lang 目录下。当采用这种方式时，每个受支持语言的应用程序都将有一个对应的 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 facade 提供的 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 facade 上的 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');

    // ...
}

如果您自定义了复数化工具的语言，应该显式地定义您的 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."
}

键 / 文件冲突

您不应定义与其它翻译文件名冲突的翻译字符串键。例如，如果为 “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') }}

替换翻译字符串中的参数

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

'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 方法接受一个闭包，闭包应该指定它负责格式化的对象类型。通常，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' => '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。在这个文件中，您只需要定义您希望覆盖的翻译字符串。未覆盖的翻译字符串将仍然从包的原始语言文件中加载。