Laravel多语言设置教程

本文深入剖析 Laravel 多语言配置中极易踩坑的核心细节：App::setLocale() 必须在请求生命周期早期调用，否则视图翻译函数（如 __() 和 @lang()）将失效；语言文件路径必须严格遵循 resources/lang/{locale} 结构，大小写敏感且不支持嵌套或自定义路径；中间件需精准插入在 EncryptCookies 之后、AddQueuedCookiesToResponse 之前，并避开提前触发翻译的逻辑；CLI 命令更需警惕 config:cache 缓存导致的环境变量失效，务必配合 config:clear 或手动设 locale。这不是简单的配置开关，而是一场贯穿请求生命周期、中间件顺序、目录规范与缓存机制的精密协同——稍有疏忽，翻译就“看不见”，只剩原始键名在控制台默默报错。

App::setLocale() 必须在请求早期调用，否则视图中 __() 和 @lang() 会读取旧语言环境——这是最常被忽略的执行时机问题。

语言文件目录结构必须严格遵循 resources/lang/{locale} 格式

Laravel 的翻译加载器只扫描 resources/lang 下以语言代码命名的子目录（如 en、zh_CN、zh-Hans），不支持任意路径或嵌套层级。

• ✅ 正确：resources/lang/zh/messages.php、resources/lang/en/auth.php、resources/lang/es.json
• ❌ 错误：resources/lang/zh-CN/messages.php（若未在配置中启用 BCP 47 解析）、lang/zh/messages.php（默认不识别）、resources/lang/zh_CN/messages/strings.php（不递归子目录）
• 注意：语言目录名需与 config/app.php 中 'locale' 值完全匹配（大小写敏感），zh-cn 和 zh_CN 被视为不同语言
• JSON 文件可直接放在语言目录下，无需 return 语句，但键名不能含点号（.），否则 __('auth.failed') 无法命中 {"auth.failed": "..."}

中间件里设语言时，顺序和位置决定成败

语言切换中间件必须在 EncryptCookies 之后、AddQueuedCookiesToResponse 之前注册，且不能晚于任何可能触发翻译逻辑的中间件（比如日志、验证、异常处理）。

• 在 app/Http/Kernel.php 的 $middlewareGroups['web'] 中检查顺序
• 若使用 session 或 cookie 读取语言偏好，确保该中间件在 StartSession 之后
• 避免在中间件中调用 trans() 或渲染视图——此时语言尚未生效，会回退到默认 locale
• URL 前缀方式（如 /zh/login）需配合路由参数绑定：Route::prefix('{locale}')->where('locale', 'zh|en|ja')，并在中间件中用 $request->route()->setParameter('locale', $locale) 显式透传

CLI 命令里翻译不生效？别只改 .env

Artisan 命令默认绕过 web 中间件栈，APP_LOCALE 环境变量虽能生效，但若已运行过 config:cache，则必须先执行 config:clear，否则缓存中的 config/app.php 仍读取旧值。

• 临时调试：直接运行 APP_LOCALE=zh php artisan tinker，再输入 __('welcome') 验证
• 自定义命令中动态设语言，应在 handle() 开头立即调用 app()->setLocale($this->option('locale') ?? 'zh')
• 添加 --locale 参数时，务必校验该语言目录真实存在：is_dir(resource_path("lang/{$locale}"))，避免静默失败
• 验证规则错误消息（如 required）依赖 resources/lang/{locale}/validation.php，缺文件会导致整个验证提示变成键名（如 "validation.required"）

关键点在于：语言上下文不是“配置一次就全局生效”，而是每次 HTTP 请求或 CLI 执行都是一次独立生命周期。漏掉中间件注册、错放执行顺序、忽略缓存机制，都会让 __() 返回原始键或 fallback 内容——这不是翻译没写，而是根本没切进去。

今天关于《Laravel多语言设置教程》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于Laravel的内容请关注golang学习网公众号！