ThinkPHP多语言怎样适配小程序_ThinkPHP移动端国际化说明【解答】

先说几个核心判断：ThinkPHP多语言本身其实不挑运行环境，小程序的适配问题，关键不在“框架能不能做”，而在于“请求语言标识怎么传”和“服务端怎么稳定地识别并加载对应语言包”。小程序没有Cookie，不走浏览器那套Accept-Language的逻辑，所以必须显式地传递参数，后端主动接管。

把逻辑拆开，其实就四个主要环节。

小程序请求必须带 lang 参数或自定义 header

默认情况下，小程序的 wx.request 并不会主动携带语言相关的信息，服务端也没法靠 $_SERVER['HTTP_ACCEPT_LANGUAGE'] 来自动识别。所以，每一次请求，都必须明确告诉服务端你要什么语言。

怎么做？两种主流方法：

• 推荐用URL查询参数，简单直接，比如 /api/user?lang=zh-cn 或者 /api/user?lang=en-us。调试、日志排查都一目了然。
• 备选方案是走自定义header，比如在请求头里加一个 lang: zh-cn，后端用 input('server.HTTP_LANG') 来读取。这种更“干净”，但也稍微麻烦一点。
• 需要特别提醒的是，尽量避免单纯依赖前端Storage存语言、再拼到URL的做法——一旦请求失败或者Storage被清除，语言参数丢失，接口就会默默退回默认语言，用户可能完全没察觉。

Lang::setLocale() 必须在中间件里提前调用

这是实战中特别容易踩坑的地方。ThinkPHP的语言切换不是简单的“全局变量赋值”，而是一次性初始化动作。如果等到控制器里才调用 Lang::setLocale()，模板渲染、验证规则很可能已经按默认语言跑完了，再改也来不及。

正确的做法是：

• 在 app/middleware.php 里注册一个自定义中间件，比如 CheckLangMiddleware。
• 中间件内部，优先读取URL参数：$lang = input('get.lang', cookie('lang') ?: session('lang'))。
• 拿到参数后，必须在允许的语言列表里校验一下：if (in_array($lang, Lang::getAllowLangList())) { Lang::setLocale($lang); }，避免随便塞个非法值就报错。
• 千万别在 config/app.php 里直接写 Lang::setLocale()——这个时机下Lang类还没初始化完，调用会静默失败，排查起来极其隐蔽。

模板与 API 返回文案要统一用 lang() 函数

小程序前端通常只接收JSON数据，所有提示文案——不管表单错误、操作成功——都应该由后端组装好再返回，不能指望小程序端自己去翻译。

具体来说：

• 控制器里别写死字符串：return json(['msg' => '用户名不能为空']); 这种写法，换个语言就得改代码。
• 必须换成：return json(['msg' => lang('user.name.require')]);，一切交给语言包。
• 验证规则也一样要语言化：['name', 'require|alphaNum', lang('user.name.require') . '|' . lang('user.name.format')]。
• 语言包的键名结构需要保持层级一致。比如在 lang/zh-cn.php 里应该是 ['user' => ['name' => ['require' => '用户名不能为空']]]。不要图省事平铺成 'user_name_require' => '...'，那样维护起来会非常痛苦。

小程序登录态下语言偏好要持久化到服务端

小程序没有传统Cookie，用户的语言选择需要跨请求保持。光靠前端缓存不太靠谱，清除Storage就没了。建议服务端绑定用户ID，把偏好记录下来。

操作流程如下：

• 用户首次设置语言时，把 $lang 写入用户表的 lang 字段，或者独立建一张偏好表记录。
• 后续请求如果没带 lang 参数，就去查库做降级处理：$lang = $user ? $user->lang : config('default_lang')。
• 这里有一个细节：不要完全依赖小程序 wx.getSystemInfoSync().language。它返回的是系统语言（比如 zh_CN），而ThinkPHP只认 zh-cn 这种格式，需要手动做一次转换。
• 转换示例：$sysLang = str_replace('_', '-', strtolower(input('server.HTTP_LANGUAGE', '')));，这样就能和语言包路径对齐了。

最后说一句实战中容易被忽略的地方：小程序真机调试时，开发者工具模拟的 Accept-Language 是不生效的，必须手动加参数才能测出效果。而如果线上环境忘了在中间件里读取 input('get.lang')，所有接口都会默默回退到 default_lang，并且没有任何报错提示。这个坑，踩过的人应该都有印象。