ThinkPHP多语言变量怎么传_ThinkPHP多语言参数传递详解【汇总】

lang() 函数只接受两个参数：第一个是语言键（字符串），第二个是可选的替换数组（关联数组）。复数语法用“item|items”格式，只有当传入严格整数 1 时才取左侧。切换语言必须在中间件开头调用 `Lang::setLang()`，且要早于任何 `lang()` 调用。语言包必须放在 `lang/zh-cn/common.php` 等小写短横路径下，文件返回数组，不能有任何输出。

很多人第一次接触 ThinkPHP 多语言时，容易把「传参」理解成类似 url() 那样拼数组或字符串。其实根本不是那回事——lang() 的核心就两步：查表 + 插值。它只接受语言键和替换数据，不存在什么“变量传递”的复杂机制。

lang() 函数的参数怎么写才有效

lang() 的参数格式非常严格：第一个参数是语言键（字符串），第二个参数是可选的替换数组。不支持 URL 查询字符串、对象、JSON 或者键值对以外的格式。

• ✅ 正确：lang('welcome_user', ['name' => 'Alice']) — 匹配语言包中 'welcome_user' => '欢迎 {name}'
• ❌ 错误：lang('welcome_user', 'name=Alice') — 第二个参数必须是关联数组，字符串会被直接忽略
• ❌ 错误：lang('welcome_user', ['name' => 'Alice', 'age' => 25]) — 如果语言包里只有 {name}，{age} 不会被处理，也不报错
• ⚠️ 注意：lang('missing_key') 在线上环境默认返回原字符串 'missing_key'，看起来像“生效了”，其实是因为没找到对应键——调试模式下才会记日志

复数语法 | 怎么用 item|items

ThinkPHP 的复数支持极简，只用竖线 | 分隔。它不依赖数字类型判断，只看传入的数值是否严格等于整数 1。

• 语言包中写：'message_count' => '1 条消息|{count} 条消息'
• 调用：lang('message_count', ['count' => 1]) → 输出 '1 条消息'
• 调用：lang('message_count', ['count' => 0]) → 输出 '0 条消息'（因为不是 1）
• 调用：lang('message_count', ['count' => '1']) → 输出 '1 条消息'（字符串 '1' 会被松散转换，但不推荐依赖）
• ⚠️ 坑点：传浮点数 1.0 或布尔 true 都不会触发左侧，只认严格整数 1

为什么 lang('xxx') 没变语言？常见执行时机错误

语言切换不是“设了就全局生效”。它其实是请求级缓存 + 提前绑定的机制。一旦 lang() 被调用过，当前请求内后续调用都走已加载的语言包，这时候再调 Lang::setLang() 也无效。

• ✅ 正确位置：在中间件 handle() 开头，并且必须在任何 lang()、__('xxx')、模板中 {:lang('xxx')} 之前执行
• ❌ 错误位置：控制器构造函数、initialize() 方法、或者响应生成后才调用 Lang::setLang('en')
• ⚠️ 特别注意：URL 参数 ?lang=en 能自动生效，是因为 ThinkPHP 内置的 Lang 中间件（需启用）在早期就解析并设置了，不是 magic，是顺序依赖
• 验证方式：在中间件里加 dump(\think\Lang::getLang());，确保输出是你期望的语言码，而不是 zh-cn

语言包路径和命名的硬性规则

ThinkPHP 对语言包位置和命名极其敏感。错一个字符、大小写、扩展名，就会静默失败——不报错，不提示，只会 fallback 到键名本身。

• ✅ 必须路径：lang/zh-cn/common.php（小写、短横线、无空格）
• ❌ 常见错误：lang/zh_CN/common.php、lang/zh-cn.php、config/lang.php、lang/zh-cn/index.php
• ✅ 文件内容必须以 return [...]; 结尾，不能有输出、不能是 JSON/YAML
• ✅ 多分组如 user.php，调用时得显式指定：lang('login_fail', [], 'user')，第三个参数是分组名
• ⚠️ Linux 服务器上 zh-CN 和 zh-cn 是不同的目录，本地开发用 Windows 可能不暴露问题，一上线就挂

容易被忽略的一点：语言包加载是一次性的。Lang::setLang() 只改变当前请求的语言标识，但不会重新 require 对应的 PHP 文件——所以切换语言之前，确保所有要用的语言包都已存在且路径正确，否则连 fallback 都没有。