根本原因是语言设置时机太晚，Lang::setLang()必须在控制器逻辑前执行；应将语言判定下沉至中间件，在路由分发前完成设置，并确保语言包在首次lang()调用前已加载。
接口返回的文案不随语言切换变化，根本原因不是配置没开，而是语言设置时机太晚或没生效——Lang::setLang()必须在控制器逻辑执行前完成，否则lang()函数拿到的仍是默认语言。
接口响应里lang()不生效的典型表现
常见错误现象包括：lang('success')始终返回中文、API返回{"msg": "success"}而非对应翻译、调试时Lang::getLangSet()打印出zh-cn但实际没加载对应语言包。
- 语言包路径写成
lang/zh_CN/common.php或lang/zh-cn.php——ThinkPHP只认lang/zh-cn/common.php这种两级目录结构 - 在控制器
__construct()里调用Lang::setLang()，但中间件已执行完毕，翻译函数早已初始化 - 用了
Lang::detect()却没传入$request，或没在中间件里主动触发，导致探测逻辑压根没跑 - 语言包文件开头有BOM头（尤其Windows下用记事本保存），PHP解析失败，静默跳过加载
如何在API接口中正确设置当前语言
必须把语言判定和设置逻辑下沉到中间件，且确保它在路由分发前执行。推荐在app\common\middleware\Lang.php中处理：
- 优先读
$request->param('lang')（如/api/user?lang=en-us） - fallback 到
$request->cookie('think_lang')或$request->session('lang') - 校验值是否在
config('app.lang_list')白名单内，非法则强制设为default_lang - 调用
\think\Lang::setLang($lang)，注意是setLang，不是setLocale（后者在6.x中已废弃） - 务必确认该中间件注册在
app/middleware.php的global数组中，且顺序靠前
lang()在JSON响应里怎么安全使用
直接在return json(['msg' => lang('login_success')])里调用没问题，但要注意几个边界：
立即学习“PHP免费学习笔记（深入）”；
- 键名必须完全一致：语言包里是
'login_success' => '登录成功'，就不能写lang('login-success')或lang('LOGIN_SUCCESS') - 嵌套结构需显式展开：
lang('user.name')要求语言包是['user' => ['name' => '用户名']]，不能简写为'user_name' => '用户名' - 占位符只支持
{key}格式，例如lang('welcome_back', ['name' => 'Tom'])对应'welcome_back' => '欢迎回来 {name}！' - 线上环境
lang()缺失key时默认返回原字符串，建议在app\common.php里加一层包装：function api_lang($key, $vars = []) { $text = lang($key, $vars); return $text === $key ? '' : $text; }，避免误传原始key
第三方扩展或自定义错误码的语言适配
框架自带的验证错误（如require|email规则）会自动走语言包，但你自定义的Validate类或业务异常里的提示不会。
- 不要在
throw new ValidateException('用户名错误')里硬编码字符串 - 改用
throw new ValidateException(lang('user_name_error'))，并确保lang('user_name_error')已在各语言包中定义 - 如果错误码来自数据库或配置项（如
err_code: 1001），可建映射表：lang/zh-cn/error.php里放['1001' => '参数格式错误']，然后lang('error.' . $code) - vendor扩展的语言包不会自动加载，需在中间件末尾手动调用
Lang::load(EXTEND_PATH . 'some-pkg/lang/' . Lang::getLangSet() . '.php')
最易被忽略的一点：语言包加载是单次请求内缓存的，Lang::setLang()切换后不会重新扫描文件，所以所有语言包必须在第一次lang()调用前就加载完毕——这意味着common.php、中间件、甚至配置加载阶段都不能依赖未声明的语言键。
