ThinkPHP 8.0 多语言（i18n）切换实现方案【全球化】

在ThinkPHP 8.0里做多语言切换，有个核心的门槛必须要跨过去：语言标识必须在语言包加载之前就生效。否则，你点按钮后 lang('submit') 显示对了，但表单验证报错、系统默认文本，全给你弹回中文——那种割裂感，懂的都懂。

所以，这篇文章就来拆解一下，怎么把这个流程走通，一次搞定。

配置语言开关与基础参数

先打开 config/app.php，确认下面三项已经摆正了位置：

• 'lang_switch_on' => true —— 注意，必须是布尔值 true，不是字符串 'true'，这俩区别很大。
• 'default_lang' => 'zh-cn' —— 默认语言，按自己的项目来。
• 'lang_list' => ['zh-cn', 'en-us', 'ja-jp'] —— 支持的语言列表，写清楚。

最关键的一步：把 'allow_url_lang' => false 给设上。为什么要关？因为如果开着，别人在 URL 后面加个 ?lang=en-us 就能把你的 Cookie 切换逻辑给劫持了，整个切换策略乱套。一定要关掉。

创建标准语言包结构

在项目根目录下新建 lang/ 文件夹，目录名必须全小写，按语言码来建子目录：

• lang/zh-cn/common.php → 里面写 return ['login' => '登录', 'submit' => '提交'];
• lang/en-us/common.php → return ['login' => 'Login', 'submit' => 'Submit'];
• lang/ja-jp/common.php → return ['login' => 'ログイン', 'submit' => '送信'];

这里有几个坑，得提前说清楚：

• 文件名必须是 common.php，不是 index.php 也不是 Common.php（大小写敏感）。
• 目录名必须全小写，ZH-CN 或 zh_CN 都不会被加载，Linux 服务器上直接静默失败——lang('login') 会原样返回 'login' 字符串，不报错、不警告，查都查不到。

编写语言切换中间件

执行命令行：php think make:middleware Lang，生成 app/middleware/Lang.php。

然后在 handle() 方法开头插入这么几行逻辑：

1. 解析 Host，去除端口干扰 —— $host = parse_url($_SERVER['HTTP_HOST'], PHP_URL_HOST) ?: $_SERVER['HTTP_HOST'];
2. 读取用户首选语言 —— $lang = $request->cookie('think_lang', $request->session('lang', 'zh-cn')); 先从 Cookie 读，没有就从 session 拿，再没有就用默认。
3. 可选的域名映射覆盖 —— 如果你有 config/lang_domains.php 文件，里面配了 ['en.example.com' => 'en-us']，那就用 $lang = $domains[$host] ?? $lang; 覆盖一下。
4. 立即生效 —— thinkLang::setLang($lang); 这步最重要，必须在语言包被加载之前调用。
5. 注册顺序要卡准 —— 把 app\middleware\Lang::class 加到 app/middleware.php 的全局中间件数组里，位置必须在 SessionInit 之后、路由调度之前。顺序错了，中间件不干活。

前端触发语言切换

前端怎么切换？两种常用方式：

方法一：纯前端写 Cookie（注意键名和路径必须严格匹配）

document.cookie = "think_lang=en-us; path=/; max-age=31536000";

方法二：调用后端接口（推荐，避免键名、路径、域名的各种小问题）

fetch('/api/setlang?lang=ja-jp', { method: 'POST' });

后端接口里只用一行代码：

cookie('think_lang', $request->param('lang'), ['expire' => 31536000, 'path' => '/']);

必须再次强调：Lang 中间件只认 cookie('think_lang')，你改成 lang 或 language 完全无效；而且中间件读取是一次性的，请求进来之后再去改 $_COOKIE 数组是没用的，别踩这个坑。

模板与代码中使用翻译

模板里直接写 {:lang('login')} 或 {__('submit')}；控制器里用 lang('welcome') 或 __('hello')。

验证规则的错误信息会自动跟随当前语言，前提是语言已经在中间件开头设好了。如果验证提示还是中文，排查时重点检查三点：中间件是否注册到位？handle() 开头有没有调用 setLang()？allow_url_lang 是不是 false？这三处对了，基本不会有问题。