Localization

• Introduction
  • 发布语言文件
  • 配置语言环境
  • 多元化语言
• 定义翻译字符串
  • 使用快捷键
  • 使用翻译字符串作为键
• 检索翻译字符串
  • 替换翻译字符串中的参数
  • Pluralization
• 覆盖包语言文件

#Introduction

Note 默认情况下，Laravel 应用程序框架不包括lang 目录。如果你想自定义 Laravel 的语言文件，你可以通过lang:publish 工匠命令。

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

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

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

或者，翻译字符串可以在放置在lang 目录。采用这种方法时，您的应用程序支持的每种语言都会在此目录中有一个对应的 JSON 文件。对于具有大量可翻译字符串的应用程序，建议使用此方法：

/lang
    en.json
    es.json

我们将讨论本文档中管理翻译字符串的每种方法。

#发布语言文件

默认情况下，Laravel 应用程序框架不包括lang 目录。如果你想定制 Laravel 的语言文件或创建你自己的，你应该脚手架lang 目录通过lang:publish 工匠命令。这lang:publish 命令将创建lang 目录并发布 Laravel 使用的默认语言文件集：

php artisan lang:publish

#配置语言环境

您的应用程序的默认语言存储在config/app.php 配置文件的locale 配置选项。您可以自由修改此值以满足您的应用程序的需要。

您可以在运行时修改单个 HTTP 请求的默认语言，使用setLocale 提供的方法App 正面：

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',

确定当前语言环境

您可以使用currentLocale 和isLocale 上的方法App facade 以确定当前语言环境或检查语言环境是否为给定值：

use Illuminate\Support\Facades\App;

$locale = App::currentLocale();

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

#多元化语言

你可以指示 Laravel 的“pluralizer”，它被 Eloquent 和框架的其他部分用来将单数字符串转换为复数字符串，使用英语以外的语言。这可以通过调用useLanguage 内的方法boot 您应用程序的服务提供商之一的方法。复数器目前支持的语言有：french,norwegian-bokmal,portuguese,spanish， 和turkish:

use Illuminate\Support\Pluralizer;

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

    // ...     
}

Warning
如果你自定义复数的语言，你应该显式定义你的 Eloquent 模型的表名.

#定义翻译字符串

#使用快捷键

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

/lang
    /en
        messages.php
    /es
        messages.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 文件：

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

密钥/文件冲突

您不应定义与其他翻译文件名冲突的翻译字符串键。例如，翻译__('Action') 对于“NL”语言环境，而 anl/action.php 文件存在但是一个nl.json 文件不存在将导致翻译器返回的全部内容nl/action.php.

#检索翻译字符串

您可以使用以下方法从您的语言文件中检索翻译字符串__ 辅助功能。如果您使用“短键”来定义您的翻译字符串，您应该将包含键和键本身的文件传递给__ 使用“点”语法的功能。例如，让我们检索welcome 翻译字符串来自lang/en/messages.php 语言文件：

echo __('messages.welcome');

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

如果您正在使用您的默认翻译字符串作为您的翻译键，您应该将字符串的默认翻译传递给__ 功能;

echo __('I love programming.');

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

如果您正在使用刀片模板引擎, 你可以使用{{ }} echo 显示翻译字符串的语法：

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

#替换翻译字符串中的参数

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

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

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

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

如果您的占位符包含所有大写字母，或者只有首字母大写，则翻译后的值将相应地大写：

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

对象替换格式

如果您尝试提供一个对象作为翻译占位符，则该对象的__toString 方法将被调用。这__toString method 是 PHP 内置的“魔法方法”之一。但是，有时您可能无法控制__toString 给定类的方法，例如当您与之交互的类属于第三方库时。

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

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

#Pluralization

多元化是一个复杂的问题，因为不同的语言有各种复杂的多元化规则；但是，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 函数检索给定“计数”的行。在此示例中，由于计数大于一，因此返回翻译字符串的复数形式：

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}目录。

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