Laravel - 本地化

Laravel - 本地化 (Localization, L10n)

Laravel 的本地化（localization）功能提供了方便的方式来检索各种语言的字符串，使您能够轻松地在应用程序中支持多种语言。语言字符串通常存储在项目根目录下的 lang 目录中的文件中（在 Laravel 9 之前是 resources/lang）。

语言文件目录结构

在 lang 目录中，您应该为应用程序支持的每种语言创建一个子目录。例如：

/lang
    /en
        messages.php
        validation.php
    /es
        messages.php
        validation.php
    /fr
        messages.php
        validation.php
    main.json  // JSON 翻译文件示例

语言文件可以是返回键名字符串数组的 PHP 文件，也可以是 JSON 文件。

PHP 语言文件

PHP 语言文件返回一个键名字符串数组。例如，lang/en/messages.php 可能如下所示：

lang/en/messages.php

<?php

return [
    'welcome' => 'Welcome to our application!',
    'greeting' => 'Hello, :name.', // 动态数据的占位符
];

以及 lang/es/messages.php（西班牙语翻译）：

lang/es/messages.php

<?php

return [
    'welcome' => '¡Bienvenido a nuestra aplicación!',
    'greeting' => 'Hola, :name.',
];

JSON 语言文件

或者，您可以在 JSON 文件中定义您的翻译字符串。对于需要在许多文件中频繁翻译的字符串，这可能更方便。例如，lang/es.json：

{
    "I love programming.": "Me encanta programar.",
    "This is a test string.": "Esta es una cadena de prueba."
}

获取翻译字符串

您可以使用 __ 辅助函数（双下划线）或 @lang Blade 指令来获取翻译字符串。__ 函数接受文件的点表示法和字符串的键作为其第一个参数。

从 PHP 文件中（例如，控制器）：

$welcomeMessage = __('messages.welcome'); // 从 messages.php 获取

// 对于 JSON 文件，直接使用键：
$loveProgramming = __('I love programming.');

从 Blade 模板中：

<h1>{{ __('messages.welcome') }}</h1>
<p>@lang('I love programming.')</p>

<!-- 使用占位符 -->
<p>{{ __('messages.greeting', ['name' => 'John']) }}</p>

复数处理 (Pluralization)

复数处理很复杂，因为不同语言有各种复杂的复数规则。您可以使用“竖线”字符（pipe character）分隔单数和复数形式来定义带有复数选项的字符串：

lang/en/messages.php

'apples' => 'There is one apple|There are :count apples',

// 在 Blade 或 PHP 中：
$message = trans_choice('messages.apples', 10); // 输出： There are 10 apples
$message = trans_choice('messages.apples', 1);  // 输出： There is one apple

trans_choice 函数（或 Lang::choice Facade 方法）用于获取这些带有复数的字符串。

设置当前区域设置 (Setting the Current Locale)

应用程序的默认语言存储在 config/app.php 配置文件中的 locale 选项中。您可以使用 App::setLocale 方法在运行时更改活动语言（active language）：

use Illuminate\Support\Facades\App;

// 在控制器方法或中间件中的示例
App::setLocale('es'); // 将当前语言设置为西班牙语

一个常见的做法是允许用户选择他们偏好的语言，通常将此偏好存储在他们的 Session 或用户资料中，然后通过中间件设置区域设置。

示例：语言切换控制器

步骤 1：确保您有语言文件。例如，创建 lang/en/demo.php 和 lang/fr/demo.php。

lang/en/demo.php

<?php return ['title' => 'Laravel Localization Example']; ?>

// lang/fr/demo.php
<?php return ['title' => 'Exemple de localisation Laravel']; ?>

步骤 2：创建一个控制器，例如 LocalizationController（php artisan make:controller LocalizationController）。

app/Http/Controllers/LocalizationController.php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Session; // 将区域设置存储到 Session 中

class LocalizationController extends Controller
{
    public function setLocale(Request $request, $locale)
    {
        if (in_array($locale, ['en', 'fr', 'es'])) { // 验证区域设置
            App::setLocale($locale);
            Session::put('locale', $locale); // 存储到 Session 中
            return redirect()->back()->with('status', "Language changed to {$locale}!");
        }
        return redirect()->back()->with('error', 'Invalid language selected.');
    }

    public function showDemoPage()
    {
        // 如果尚未通过 URL 参数设置区域设置，可选地从 Session 中获取
        // if (Session::has('locale')) {
        //     App::setLocale(Session::get('locale'));
        // }
        return view('localization_demo'); // 我们将创建此视图
    }
}

步骤 3：创建一个简单的 Blade 视图 resources/views/localization_demo.blade.php：

resources/views/localization_demo.blade.php

<!DOCTYPE html>
<html>
<head>
    <title>@lang('demo.title')</title>
</head>
<body>
    <h1>@lang('demo.title')</h1>
    <p>
        Current locale: {{ App::getLocale() }}
    </p>
    <p>
        <a href="{{ url('locale/en') }}">English</a> |
        <a href="{{ url('locale/fr') }}">Français</a> |
        <a href="{{ url('locale/es') }}">Español</a> (添加 'es' 文件才能完全工作)
    </p>

    @if (session('status'))
        <div style="color: green;">{{ session('status') }}</div>
    @endif
    @if (session('error'))
        <div style="color: red;">{{ session('error') }}</div>
    @endif
</body>
</html>

步骤 4：在 routes/web.php 中添加路由：

use App\Http\Controllers\LocalizationController;

Route::get('locale-demo', [LocalizationController::class, 'showDemoPage']);
Route::get('locale/{locale}', [LocalizationController::class, 'setLocale']);

步骤 5：通过访问 URL 进行测试：

• http://localhost:8000/locale-demo（将使用默认或 Session 中的区域设置）
• http://localhost:8000/locale/en（然后刷新 locale-demo 或导航到它）
• http://localhost:8000/locale/fr（然后刷新 locale-demo 或导航到它）

您将看到标题和状态消息根据所选语言发生变化。此示例还展示了如何将用户偏好的区域设置存储到 Session 中。

回退语言（Fallback Language）：您还可以在 config/app.php 中配置 fallback_locale。当活动语言不包含给定翻译字符串时，将使用此语言。

有关更高级的本地化主题，例如覆盖 vendor 包的语言文件或使用短键，请参阅官方 Laravel 本地化文档。