如何在 Laravel 中正确加载多语言资源文件
Laravel 的国际化（i18n）依赖 resources/lang 下的 PHP 数组文件或 JSON 文件，不是靠修改配置开关就能生效的。关键在于：语言包必须按约定结构存放，且键名需全局唯一、避免嵌套过深。
常见错误是把中文翻译直接写成 zh-CN.php，但 Laravel 默认只识别 zh_CN 或 zh 这类下划线/短横分隔的 locale 标识；同时，zh_CN 目录下必须有对应键的数组，例如：
// resources/lang/zh_CN/messages.php
return [
'welcome' => '欢迎来到网站',
'login' => '登录',
];
- 语言目录名必须与
App::setLocale()或配置中使用的 locale 完全一致（区分大小写） - 推荐优先使用简写（如
zh），避免因系统 locale 设置差异导致 fallback 失败 - 不要在语言文件里写逻辑或调用函数——它们是纯数据，PHP 解析失败会导致整个请求 500
怎么动态切换语言而不刷新页面
前端切换语言本质是改后端的 session 或 cookie 中的 locale 值，再让后续请求带上它。Laravel 自带的 App::setLocale() 只影响当前请求生命周期，不持久化。
最稳妥的做法是：用一个路由接收语言参数，存入 session，并重定向回原页（保持 UX 连贯）。示例：
// routes/web.php
Route::get('/locale/{locale}', [LanguageController::class, 'switch'])->name('locale.switch');
// LanguageController.php
public function switch(string $locale)
{
if (in_array($locale, config('app.locales', ['en', 'zh']))) {
session(['locale' => $locale]);
return redirect()->back();
}
abort(400);
}
- 别用 cookie 直接存 locale 并依赖中间件自动 set —— 某些浏览器对第三方上下文中的 cookie 限制变严，容易静默失效
- session 方式需确保
SESSION_DRIVER配置正常（如redis或database），文件驱动在高并发下可能丢数据 - 前端按钮链接应为
/locale/zh而非?lang=zh，避免 SEO 和缓存污染
为什么 __('key') 不生效或返回 key 本身
这是最常被忽略的底层机制问题：__() 是 Laravel 提供的辅助函数，它内部调用 trans()，而后者依赖当前 locale + 当前已加载的语言包。如果返回原 key，说明没找到翻译，原因通常有三个：
- 当前 locale 是
en，但你只写了zh_CN/messages.php，没有en/messages.php（哪怕内容和 key 一样也要存在） - 语言包文件名拼错，比如写成
message.php而非messages.php，Laravel 默认只扫描messages.php和auth.php等预设名 - 使用了
trans('user.name')但resources/lang/zh_CN/user.php里定义的是return ['name' => '姓名']—— 正确写法是trans('user.name')对应user.php中的['name' => '姓名']，层级不能错
调试时可临时加一行：dd(app()->getLocale(), trans('welcome')); 看实际解析出的值和 locale 是否匹配。
JSON 语言文件适合什么场景
当项目需要支持大量前端 JS 翻译（比如 Vue 组件内文案），或语言项极多、需交由非 PHP 开发者维护时，用 JSON 更合适。Laravel 6+ 原生支持 resources/lang/en.json 这类文件。
- JSON 文件不能有注释、不能用 PHP 表达式，但可被 Webpack/Vite 直接导入，适合前后端共用一套词条
- 注意：JSON 中的 key 必须是字符串，且不能含点号（
.）—— 否则__('auth.failed')会找不到，因为 JSON 不支持嵌套路径语法 - 混合使用 PHP 数组和 JSON 时，Laravel 会优先加载 PHP 文件；若想强制用 JSON，得删掉同名 PHP 文件，否则 PHP 版本永远覆盖 JSON
真正麻烦的从来不是“怎么切”，而是“词条一致性”和“上下文丢失”——比如同一个 name 在用户资料页是“姓名”，在订单页却是“收货人姓名”，这种差异必须靠命名区分（profile.name vs order.shipping_name），而不是指望翻译文件里硬塞逻辑。
