Laravel 本地化 i18n 多语言方案国际化

Laravel多语言需用Route::prefix('{locale}')->middleware('setlocale')确保locale早期生效，中间件校验白名单并调用App::setLocale()，命名路由必须用route('name', ['locale'=>'xx'])生成URL。

__('key') 返回原始字符串？不是没配好，是 locale 没在请求早期生效。

路由前缀必须用 Route::prefix('{locale}') + 中间件

不加前缀、不走中间件，app()->setLocale() 就算手动调了也晚——视图渲染和验证消息已按默认语言生成。

• routes/web.php 顶部写 Route::prefix('{locale}')->middleware('setlocale')，别漏掉 {locale} 占位符
• app/Http/Middleware/SetLocale.php 里必须验证 $request->locale 是否在 config('app.locales') 白名单中，否则直接 404 或 fallback 到 config('app.fallback_locale')
• 命名路由生成 URL 时，必须用 route('home', ['locale' => 'ja'])，硬拼 /ja/home 会绕过路由匹配，导致 404
• Laravel 11 要求所有本地化路由包裹在 Route::localized()（需 mcamara/laravel-localization v2.0+）

resources/lang/{locale}/ 目录结构不能错

文件放错位置，__('auth.failed') 就永远返回 auth.failed 字符串本身。

• 必须是 resources/lang/en/auth.php，不是 resources/lang/en/messages.php —— 后者只管 __('welcome') 这类通用键
• JSON 格式成 Laravel 11 首选：resources/lang/zh.json 直接存扁平键值对，但禁止 BOM，否则 500
• PHP 文件必须以 <?php return [...]; 开头，且不能有输出或注释在 <?php 前
• php artisan lang:publish 只复制框架内置 en 文件，新增语言如 ja 得手动建目录、复制改写

Blade 里变量插值要用 __()，不是 @lang

@lang('validation.custom.password.min') 不支持传参，它只是原样输出字符串；占位符替换必须靠 __() 的第二个参数。

• 语言文件里写 'custom_message' => 'The :attribute must be at least :min characters.'
• 模板里用 {{ __('custom_message', ['attribute' => 'password', 'min' => 8]) }}
• 验证规则自动注入的 :attribute 是框架行为，自定义提示仍要显式传参，__('validation.custom.password.min', ['min' => 8]) 才生效

缓存开启后改语言文件必须清缓存

APP_DEBUG=false 时，Laravel 会缓存翻译和视图，改了 resources/lang/zh/validation.php 也看不到效果。

• 运行 php artisan view:clear 清视图缓存
• 运行 php artisan config:clear 清配置缓存（语言加载路径依赖 config）
• 别只清 cache:clear，它不包含翻译缓存
• 开发阶段建议保持 APP_DEBUG=true，避免反复清缓存打断节奏

关键点不在“怎么写翻译”，而在“谁在什么时候读取它”——语言切换必须发生在路由解析之后、控制器执行之前，且路径、命名空间、缓存三者任何一个出问题，都会让 __() 静默回退到原始键名。