Laravel API 多语言响应需通过 Accept-Language 头或 locale 参数设置 locale，校验白名单，规范 lang 目录结构，并在响应前调用 App::setLocale() 确保 __() 正确翻译。
如果您开发 Laravel API 接口，但返回的提示消息（如验证错误、成功文案）始终为默认语言，无法随客户端请求语言动态切换，则可能是由于未在请求生命周期中显式设置 locale 或语言文件未按规范组织。以下是实现 API 多语言响应的具体方法：
一、通过 Accept-Language 请求头自动识别并设置 locale
该方法利用客户端浏览器或移动端发出的 Accept-Language HTTP 头（如 zh-CN,zh;q=0.9,en;q=0.8），安全提取首选语言，并校验其是否在白名单内，避免非法 locale 注入。此方式无需修改 URL 或客户端逻辑，符合 RESTful 设计原则。
1、在 app/Http/Middleware 目录下新建 LocaleMiddleware.php 文件，内容如下：2、在中间件 handle 方法中调用 $request->getPreferredLanguage(['en', 'zh_CN', 'ja']) 获取合法语言标识。
3、将结果传入 App::setLocale()，确保后续所有 __() 调用均基于该 locale 查找翻译。
4、在 app/Http/Kernel.php 的 $middlewareGroups['api'] 数组中注册该中间件。
5、确认 config/app.php 中 'available_locales' => ['en', 'zh_CN', 'ja'] 已正确定义且与 lang/ 目录子目录名完全一致。
二、通过 URL 查询参数 locale 动态覆盖语言环境
该方法适用于需要手动调试、前端强制切换语言或嵌入第三方平台的场景。关键在于对参数值进行严格白名单校验，防止因非法 locale 导致 InvalidArgumentException 或静默回退到默认语言。
1、在路由定义中添加可选 locale 参数，例如 Route::middleware('api')->group(function () { Route::get('/users', [UserController::class, 'index']); });2、在控制器构造函数或方法开头读取 request()->query('locale')。
3、使用 in_array($locale, config('app.available_locales'), true) 判断是否合法。
4、若合法，则执行 App::setLocale($locale)；否则忽略该参数，维持当前 locale。
5、
必须在构造响应数组前完成 locale 切换，不可在 response()->json() 内部临时调用。
三、在 FormRequest 中定制多语言验证错误消息
当需为同一验证失败字段同时提供多种语言错误文案（如中英文并列），或避免 failedValidation 阶段已固化单语言 MessageBag 的限制时，应重写 messages() 方法，直接注入多语言键值结构，绕过默认语言绑定机制。
1、在 FormRequest 类中定义 public function messages() { return [ 'email.required' => ['zh_CN' => '邮箱不能为空', 'en' => 'Email is required'] ]; }。
2、在 failedValidation 方法中，遍历 $validator->getMessageBag()->getMessages()，对每个字段错误数组进行语言键展开。
3、将处理后的多语言错误结构整合进统一响应 data 字段，例如 'errors' => ['email' => ['zh_CN' => '邮箱不能为空', 'en' => 'Email is required']]。
4、
禁止在模型 accessor、全局作用域或 Eloquent Resource 的 toArray() 中调用 __()。
四、确保语言文件路径与命名严格合规
Laravel 对 lang/ 目录结构极其敏感，任何偏差（如大小写错误、中划线代替下划线、目录名与 config/locale 不匹配）都将导致 __() 静默回退至默认语言且不报错，极难排查。
1、语言目录必须位于 resources/lang/ 下，子目录名须与 config/app.php 中 'locale' 值完全一致，例如 'zh_CN' 对应 resources/lang/zh_CN/。
2、每个子目录内必须包含 messages.php 文件，且该文件必须返回关联数组，例如 return ['welcome' => '欢迎'];。
3、验证类错误需额外提供 validation.php，其键名结构须与验证规则对应，例如 'required' => ':attribute 为必填项'。
4、
中文 locale 强烈推荐使用 zh_CN 而非 zh，因多数安卓设备及 Windows 系统发送的 Accept-Language 含地区码。
五、在 JSON 响应构造阶段强制执行 locale 切换
API 返回 JSON 时，__('success') 等翻译函数是运行时求值，若在 response()->json() 内部调用，此时请求上下文可能已销毁或 locale 未生效，导致返回默认语言内容。
1、在控制器方法体起始位置即调用 App::setLocale($locale)，而非放在 return 语句中。
2、所有需翻译的字段（如 'message' => __('user_created')、'data' => ['name' => __('admin')]）必须在此之后生成。
3、若使用 Eloquent Resource，应在 new UserResource($user) 构造时传入当前 locale，而非在 toArray() 中调用 __()。
4、
禁止在模型属性访问器（accessor）中使用 __()，因其无请求上下文，locale 恒为 config('app.locale')。