本地化

• 简介
  • 发布语言文件
  • 配置区域设置
  • 复数语言
• 定义翻译字符串
  • 使用短键
  • 使用翻译字符串作为键
• 检索翻译字符串
  • 替换翻译字符串中的参数
  • 复数形式
• 覆盖包语言文件

简介

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

配置区域设置

应用的默认语言存储在 `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;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pluralizer::useLanguage('spanish');
 
    // ...
}

定义翻译字符串

使用短键

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

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

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

<?php
 
// lang/en/messages.php
 
return [
    'welcome' => 'Welcome to our application!',
];

使用翻译字符串作为键

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

因此，Laravel 还支持使用字符串的“默认”翻译作为键来定义翻译字符串。使用翻译字符串作为键的语言文件存储在 `lang` 目录中的 JSON 文件中。例如，如果你的应用有西班牙语翻译，你应该创建一个 `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` 方法是 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。在这个文件中，你只需要定义你希望覆盖的翻译字符串。任何你没有覆盖的翻译字符串仍然会从软件包的原始语言文件中加载。