如何使用ThinkPHP多语言标签输出多语言变量？

本文共计1031个文字，预计阅读时间需要5分钟。

ThinkPHP 是一款流行的 PHP 开源框架，它简化了 PHP 项目的开发过程。以下是其基本内容：

模板中输出多语言变量只能用 {:lang('key')} 或 {:__('key')}

ThinkPHP 模板引擎不识别语言 key 为普通变量，{$hello_world} 这类写法无效——它会去查 $hello_world 变量，而不是查语言包。正确方式是调用函数并包裹在 {:...} 中：

• {:lang('welcome_message')} —— 最常用，推荐
• {:__('welcome_message')} —— 助手函数别名，效果一致
• 支持占位符：{:lang('hello_user', ['name' => $user['name']])}，对应语言包中 'hello_user' => '你好，{name}！'
• 不支持 {:lang($key)} 这种动态 key，因为模板编译期无法解析变量值；如需动态，应在控制器里先计算好再 assign

lang() 在控制器/模型里调用要早于任何视图渲染

语言切换状态在请求生命周期中是单次设定的，lang('xxx') 的结果取决于当前已激活的语言包。如果在控制器方法末尾才调用 Lang::setLang('en-us')，前面已执行的 lang('xxx') 仍按旧语言返回。

• 务必在中间件（如自定义 App\Middleware\LangSwitch）中完成语言判定和 Lang::setLang() 设置
• 不要在构造函数里设语言，__construct() 执行时中间件尚未运行，Lang 状态仍是默认值
• 模型验证提示（如 'required' => ':attribute 不能为空'）也走同一套语言系统，所以模型层的 lang() 调用同样受中间件设置影响

语言包路径和文件名错一个字母就静默失效

ThinkPHP 对语言包路径极其敏感，错误不会抛异常，只会回退到默认语言或原 key 字符串，极难排查。

立即学习“PHP免费学习笔记（深入）”；

• 路径必须是 lang/zh-cn/common.php，不是 lang/zh_CN/common.php、lang/zh-cn.php 或 config/lang.php
• Linux 服务器上 zh-CN 和 zh-cn 是不同目录，后者才有效
• 文件必须以 UTF-8 无 BOM 格式保存，带 BOM 会导致 return [...] 前有不可见字符，PHP 解析失败，语言包为空
• 数组键名要完全一致：控制器里写 lang('save_success')，语言包里就必须有 'save_success' => '保存成功'，多空格、大小写、下划线差异都会导致 fallback

常见错误现象：页面显示 save_success 而不是“保存成功”

这不是配置没生效，而是语言包根本没加载进来。最可能的原因是：

• 语言包文件放在了 app/lang/zh-cn.php（应为 lang/zh-cn/common.php）
• 当前请求语言被设为 en-us，但 lang/en-us/common.php 不存在且未配置 allow_lang_list，框架自动降级到默认语言包，而你只写了 zh-cn 包
• 开启了 use_cookie 但 Cookie 中存的是过期/非法值（如 lang=xx），又没配 allow_lang_list，结果被忽略，fallback 到 default_lang
• 调试模式关闭时，缺失 key 不报日志，建议上线前用脚本扫描所有 lang() 调用点，比对语言包 keys 是否全覆盖

真正麻烦的不是怎么写，而是语言状态在中间件、请求参数、Cookie、Session、配置项之间隐式流转——任何一个环节断链，输出就变回 key。动手前先确认 Lang::getLang() 返回值是否符合预期，比盲目改模板更省时间。