laravel11设置中文语言包

news2025/2/28 4:57:29

安装中文语言包
Laravel 11 默认没有内置完整中文语言包，推荐使用第三方维护的完整翻译：

# 通过 Composer 安装语言包
composer require laravel-lang/common --dev

# 发布中文语言文件到项目
php artisan lang:add zh_CN

这会自动将中文语言文件生成到 lang/zh_CN 目录。

配置应用语言
修改 .env 文件设置默认语言：

APP_LOCALE=zh_CN

或直接在 config/app.php 中配置：

'locale' => 'zh_CN',
'fallback_locale' => 'en',

验证器错误响应格式（API适配）
在前后端分离架构中，需确保验证错误返回标准化的 JSON 格式。修改 app/Exceptions/Handler.php：

use Illuminate\Validation\ValidationException;

public function render($request, Throwable $e)
{
    if ($e instanceof ValidationException) {
        return response()->json([
            'code' => 422,
            'message' => '参数验证失败',
            'errors' => $e->errors(),
        ], 422);
    }

    return parent::render($request, $e);
}

自定义字段名称映射
在 lang/zh_CN/validation.php 中配置 attributes 部分：

'attributes' => [
    'email' => '邮箱',
    'password' => '密码',
    'user.name' => '用户姓名', // 支持嵌套字段
],

自定义验证消息
(1) 全局覆盖：在语言文件中修改

// lang/zh_CN/validation.php
return [
    'required' => ':attribute 是必填字段',
    'email' => ':attribute 必须是有效的邮箱格式',
    // 其他规则...
];

(2) 局部覆盖：在验证时指定

Validator::make($request->all(), [
    'email' => 'required|email',
], [
    'email.required' => '必须填写邮箱地址',
    'email.email' => '邮箱格式不合法',
]);

验证器测试示例
发送一个无效请求（如缺少必填字段），将收到以下结构化响应：

{
    "code": 422,
    "message": "参数验证失败",
    "errors": {
        "email": [
            "邮箱 是必填字段"
        ],
        "password": [
            "密码 是必填字段"
        ]
    }
}

常见问题排查
问题1：语言文件未生效
✅ 检查文件路径是否为 lang/zh_CN/validation.php
✅ 执行 php artisan config:clear 清除配置缓存
问题2：字段名称未翻译
✅ 确保 attributes 数组中键名与请求字段名完全一致
✅ 嵌套字段使用点语法（如 user.address.street）

问题3：自定义规则消息
对于自定义验证规则，在规则类中添加：

class CustomRule implements Rule
{
    public function message()
    {
        return trans('validation.custom_rule'); // 在语言文件中定义
    }
}

高级用法：动态切换语言
若需支持多语言，可在中间件中动态设置：

// 创建中间件 SetLocale
public function handle($request, Closure $next)
{
    $lang = $request->header('Accept-Language', 'zh_CN');
    App::setLocale($lang);
    return $next($request);
}

// 在 Kernel.php 注册中间件
protected $middlewareGroups = [
    'api' => [
        \App\Http\Middleware\SetLocale::class,
        // ...
    ],
];

通过以上配置，Laravel 11 API 项目即可实现：