如何配置ThinkPHP多语言API以适配伪静态接口？

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

ThinkPHP 是一款流行的 PHP 开源框架，它简化了 PHP 开发流程，提高了开发效率。该框架遵循 MVC 架构模式，具有以下特点：

API 请求里怎么指定语言

前端应在请求头中携带 Accept-Language，或统一用自定义 Header，比如 X-Language: en-us。框架默认只认 Accept-Language，但该字段浏览器自动带、API 客户端未必可控，所以更推荐显式 Header。

• 后端需在中间件中提前读取并设置语言，不能等控制器才处理，否则 lang() 已按默认语言渲染完毕
• 不要依赖 Lang::setLang() 在控制器里调用——它只影响后续调用，对当前请求中已初始化的语言包无效
• 若用 Accept-Language，注意 ThinkPHP 的解析逻辑只取第一个匹配项（如 zh-CN,zh;q=0.9,en-US;q=0.8 只取 zh-cn），且严格比对 LANG_LIST 中的值（zh-cn ≠ zh_CN）

lang/ 目录结构和命名必须严格匹配

API 场景下语言包仍须放在 lang/ 下，子目录名必须小写、用短横线分隔（zh-cn、en-us），不能是下划线或大写；文件名固定为 common.php 或按分组命名（如 api.php），但必须在调用前显式加载。

• 如果 API 专用语言项较多，建议单独建 lang/zh-cn/api.php，再用 Lang::load('zh-cn.api') 加载，避免和前台 common.php 混用
• 切勿用 JSON/YAML：ThinkPHP 的 Lang 类只支持 PHP 返回数组，其他格式会静默失败
• 文件开头不能有 BOM，否则 require 报错或返回空数组，调试时 var_dump(include 'lang/zh-cn/common.php') 是最快验证方式

伪静态路由下 lang 参数怎么透传

当启用伪静态（如 route_rule 或 url_html_suffix），URL 形如 /api/user/list.html，此时 ?lang=en-us 会被 Nginx/Apache 截断或忽略，无法触发框架自动识别。

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

• 解决方案一：把语言作为路径段，例如 /en-us/api/user/list，然后在路由定义中捕获：Route::rule('[:lang]/api/:controller/:action', 'api/:controller/:action')->ext('html');，再在中间件中用 $request->param('lang') 设置
• 解决方案二：改用 Header 传递，彻底绕过 URL 限制（推荐）
• 切忌在伪静态规则里强行重写 lang=xxx 到 query string——部分 Swoole 或 FastCGI 环境下 $_GET 不可靠，且与 Lang 类的检测顺序冲突

lang() 函数在 JSON 响应里怎么安全使用

lang() 返回字符串，直接用于 json() 响应没问题，但要注意占位符和复数语法在 API 中容易出错。

• 占位符如 lang('user_not_found', ['id' => 123]) 依赖 strtr()，若传入非字符串值（如 null）会导致空输出，建议先 isset() 或强制转字符串
• 复数语法 lang('item|items', $count) 要求语言包里对应键是竖线分隔的两个值，例如 'item|items' => '条|条'，但英文需区分单复数，实际应写成 'item|items' => 'item|items'，否则翻译错乱
• API 错误码文案建议单独抽离，不要混在 common.php 里，可用 lang('api.user_not_found') 这种命名空间风格，配合 Lang::load('zh-cn.api') 按需加载

最易被忽略的是中间件执行时机——语言必须在 app_init 或 app_begin 阶段就设置好，而不是等到控制器或 json() 执行时才调 Lang::setLang()。一旦 Lang 实例完成初始化，后续设置只影响新请求。