Laravel多语言路由：实现全局Locale参数与中间件集成

聖光之護

发布时间：2025-12-07 21:32:32

214人浏览过

来源于php中文网

原创

laravel多语言路由：实现全局locale参数与中间件集成

本文详细介绍了如何在Laravel应用中为所有路由添加一个默认的`locale`参数，以支持多语言网站。通过结合路由组的`prefix`功能和自定义中间件，我们能够优雅地处理URL中的语言前缀，自动设置应用程序的语言环境，并确保路由的灵活性和可维护性。

1. 理解多语言路由的需求

在构建多语言网站时，一个常见的需求是在URL中包含当前语言环境（locale），例如 http://localhost/en/blog 或 http://localhost/fa/blog。这不仅有助于用户识别当前语言版本，也方便搜索引擎优化。为了避免在每个路由定义中手动添加语言参数，我们可以利用Laravel的路由组功能来统一管理。

2. 使用路由组定义语言前缀

Laravel的路由组允许我们对一组路由应用共同的属性，例如前缀、中间件或命名空间。对于多语言路由，我们可以使用prefix('{locale}')来为所有包含在组内的路由添加一个动态的语言前缀。

以下是一个基本的路由组定义示例：

// routes/web.php
use App\Http\Controllers\HomeController;
use App\Http\Controllers\PostController;

Route::prefix('{locale}')->group(function() {
    Route::get('/', [HomeController::class, 'index'])->name('home');
    Route::get('/blog', [PostController::class, 'index'])->name('blog');
    // 其他需要语言前缀的路由...
});

在这个配置中：

Route::prefix('{locale}')：指示Laravel将URL的第一个段作为locale参数。
group(function() { ... })：包含所有需要此语言前缀的路由。

现在，访问 /en 或 /fa/blog 这样的URL，Laravel会将 en 或 fa 捕获为 locale 参数。

3. 创建并配置语言环境中间件

仅仅在URL中捕获locale参数是不够的，我们还需要一个机制来读取这个参数，验证其有效性，并据此设置应用程序的语言环境。这可以通过创建一个自定义中间件来实现。

3.1 定义中间件

首先，通过Artisan命令创建一个新的中间件：

百宝箱

百宝箱是支付宝推出的一站式AI原生应用开发平台，无需任何代码基础，只需三步即可完成AI应用的创建与发布。

下载

php artisan make:middleware SetLocale

然后，编辑生成的 app/Http/Middleware/SetLocale.php 文件：

// app/Http/Middleware/SetLocale.php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Illuminate\Support\Facades\Config;

class SetLocale
{
    /**
     * 处理传入的请求。
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure(\Illuminate\Http\Request): (\Illuminate\Http\Response|\Illuminate\Http\RedirectResponse)  $next
     * @return \Illuminate\Http\Response|\Illuminate\Http\RedirectResponse
     */
    public function handle(Request $request, Closure $next)
    {
        // 从URL的第一个段获取locale参数
        $locale = $request->segment(1);

        // 获取应用程序支持的语言列表 (例如在 config/app.php 中定义 'locales' => ['en', 'ar', 'fa'])
        $supportedLocales = Config::get('app.locales', ['en']); // 默认支持英文

        // 验证locale是否有效，如果无效则抛出404错误
        if (!is_null($locale) && !in_array($locale, $supportedLocales)) {
            abort(404);
        }

        // 根据locale设置HTML的文本方向 (ltr 或 rtl)
        // 假设 'en' 是从左到右，其他是根据需要设置
        $html_dir = in_array($locale, ['en']) ? 'ltr' : 'rtl';
        Config::set('app.html_dir', $html_dir);

        // 设置应用程序的语言环境
        App::setLocale($locale);

        return $next($request);
    }
}

3.2 配置支持的语言列表

为了让 SetLocale 中间件正常工作，您需要在 config/app.php 文件中添加一个 locales 数组，列出您的应用支持的所有语言：

// config/app.php
return [
    // ... 其他配置
    'locales' => ['en', 'ar', 'fa'], // 根据您的需求添加支持的语言
    'html_dir' => 'ltr', // 用于在视图中动态设置HTML dir属性
    // ...
];

4. 将中间件应用于路由组

现在，我们将 SetLocale 中间件应用到包含语言前缀的路由组。这样，任何访问这些路由的请求都会先经过中间件处理，确保语言环境在路由处理之前被正确设置。

// routes/web.php
use App\Http\Controllers\HomeController;
use App\Http\Controllers\PostController;
use App\Http\Middleware\SetLocale; // 导入中间件

Route::prefix('{locale}')->middleware(SetLocale::class)->group(function() {
    Route::get('/', [HomeController::class, 'index'])->name('home');
    Route::get('/blog', [PostController::class, 'index'])->name('blog');
    // 其他需要语言前缀的路由...
});

通过这种方式：

用户访问 http://localhost/project/en/blog。
SetLocale 中间件被执行，从URL中提取 en。
中间件验证 en 是否在 config('app.locales') 中。
中间件设置 App::setLocale('en') 和 Config::set('app.html_dir', 'ltr')。
请求继续处理 blog 路由，此时应用程序的语言环境已经设置为 en。

5. 生成带语言参数的URL

在视图或控制器中生成带语言参数的URL时，您需要确保传递 locale 参数。

// 例如，生成 'home' 路由的URL
// 获取当前语言环境
$currentLocale = App::getLocale();

// 生成当前语言的URL
$homeUrl = route('home', ['locale' => $currentLocale]); // 例如 /en

// 生成其他语言的URL
$faHomeUrl = route('home', ['locale' => 'fa']); // 例如 /fa

为了简化URL生成，您可以考虑创建一个辅助函数或利用Laravel的URL生成事件来自动添加当前语言环境。

6. 注意事项与最佳实践

默认语言处理： 如果您的网站允许没有语言前缀的URL（例如 /blog），您可能需要为这些路由定义一个单独的组，或者在SetLocale中间件中处理$locale为空的情况，并设置一个默认语言。
语言切换： 提供一个语言切换器，让用户能够轻松切换语言。切换时，需要重新生成当前页面的URL，并替换其中的locale参数。
路由命名： 确保路由名称是唯一的，即使在不同的语言前缀下也是如此。
视图中的语言文本： 使用Laravel的本地化功能（__('key') 或 @lang('key')）来显示多语言文本。
HTML dir 属性： 在您的主布局文件中，可以使用 config('app.html_dir') 来动态设置 <html> 标签的 dir 属性，以支持从右到左（RTL）的语言。

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}" dir="{{ config('app.html_dir') }}">
<head>
    <!-- ... -->
</head>
<body>
    <!-- ... -->
</body>
</html>