Laravel本地化（Localization）与多语言API-php教程-PHP中文网

api多语言失效的根本原因是app::setlocale()未在请求生命周期早期、api中间件中显式调用，且未与accept-language解耦；必须通过localemiddleware校验并设置locale，否则__(),验证消息等均保持默认语言。

laravel本地化（localization）与多语言api

API 接口返回的错误提示、成功消息始终是英文，或切换语言后没生效——根本原因不是翻译文件写错了，而是 App::setLocale() 没在正确时机、正确作用域下执行，且未与请求上下文解耦。

这是最常见错觉：以为浏览器带了 Accept-Language: zh-CN，Laravel 就会自动切语言。实际不会。__() 完全依赖当前请求生命周期内最后一次 App::setLocale() 的调用结果，而框架默认不为 API 请求做这件事。

必须显式注册中间件（如 LocaleMiddleware）到 $middlewareGroups['api']，不能只加在 web 组
中间件里要用 $request->getPreferredLanguage(['en', 'zh_CN', 'ja']) 提取并校验，不能直接取 header 字符串——否则可能传入 zh-CN;q=0.9 这类非法值导致 InvalidArgumentException
config('app.available_locales') 必须与 resources/lang/ 下的目录名完全一致（比如用 zh_CN 就不能写成 zh-cn 或 zh）
验证错误消息（如 validation.php）也受此 locale 控制，但 FormRequest 的 messages() 方法会在 failedValidation 之前执行，此时 locale 若未设置，就会固化为默认值

别试了。route('api.users.index') 永远输出 /api/users，哪怕你在中间件里调了 App::setLocale('zh_CN')。因为 route() 只看路由定义和传参，和当前 locale 无关。

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

API 路由通常不用前缀，route() 本就不该也不需要生成带语言的 URL
如果你在响应里返回跳转链接（如 next 字段），应手动拼接或使用辅助函数，例如：url('/api/users?locale=' . app()->getLocale())
若硬要前缀（如 /zh/api/users），得把 {locale} 显式写进路由定义，并在每个 route() 调用时传 ['locale' => ...]——这对纯 API 场景既冗余又易错

这是因为 Laravel 的验证器在构造 MessageBag 时就已锁定语言环境。一旦进入 failedValidation()，再调 App::setLocale() 已无效。

解决方案是重写 FormRequest 的 messages() 方法，直接返回多语言键值对：return ['email.required' => __('validation.email.required')];
不要在 rules() 里用 __('validation.email.required') ——它会被当字符串字面量解析，不触发翻译
更稳妥的做法是在控制器中手动验证：$validator = Validator::make(...)->setLocale(app()->getLocale());，再调 $validator->validate()
注意：自定义 messages() 后，attributes() 和 values() 仍需单独处理，它们不自动继承 locale

客户端传 ?locale=fr，而你的白名单只有 ['en', 'zh_CN']，如果代码里没做严格校验，App::setLocale('fr') 会抛出异常，或静默降级到 fallback_locale，前端却收不到任何提示。

务必用 in_array($locale, config('app.available_locales'), true) 校验，true 参数防止 '1' == 'en' 类型混淆
校验失败时，不要跳过设置，而是明确设回当前有效 locale（如从 session 读）或返回 400 错误：throw new HttpResponseException(response()->json(['message' => __('errors.invalid_locale')], 400));
避免在响应体里混用语言：比如 locale=zh 时，却因某处漏设 App::setLocale()，导致 __('auth.failed') 返回英文，而其他字段是中文

真正容易被忽略的是：API 的多语言本质是「每请求一次语言上下文」，不是「用户一次选择永久生效」。它不依赖 session、不修改全局配置、不生成带前缀的 URL——所有逻辑必须收敛在单次请求的中间件 → 控制器 → 响应链中，少一步，就断一环。