Webman的i18n.php配置文件必须位于config/目录下且不可改名，需正确定义default_locale、available_locales和translation_file_paths；语言文件须为{locale}.php格式并严格匹配命名与内容规范，每次请求须显式调用Webman\I18n::setLocale()初始化上下文，否则i18n()静默失效。
Webman 的 i18n.php 配置文件必须存在且路径正确
Webman 不像 Laravel 那样自动扫描 resources/lang，它依赖显式配置的 i18n.php 文件来驱动国际化。这个文件必须放在 config/ 目录下，不能少，也不能改名。
常见错误是把配置写在 app.php 或 middleware.php 里，结果 i18n() 函数调用时找不到语言包路径，直接返回原字符串或报错。
-
default_locale值要和你实际语言目录名完全一致（如zh_CN，不是zh或zh-cn） -
available_locales是白名单，不在列表里的语言即使 URL 传了也会被忽略 -
translation_file_paths必须是绝对路径数组，推荐用__DIR__ . '/../lang'，别用相对路径或硬编码./lang - 如果项目用了多级目录结构（比如 Webman + Docker），
../lang可能指向错位置，建议先var_dump(realpath(__DIR__ . '/../lang'))确认真实路径
i18n() 函数不生效？检查语言文件命名与内容格式
Webman 的 i18n() 默认读取的是 PHP 数组文件，不是 .po 或 .yaml。文件必须严格按 {locale}.php 命名，例如 zh_CN.php、en_US.php，大小写和下划线都不能错。
文件内容必须是纯返回数组，不能有输出、不能含 BOM、不能带多余空格或注释（尤其是 UTF-8 BOM，会导致解析失败）：
立即学习“PHP免费学习笔记（深入）”；
return [
'welcome' => '欢迎',
'hello' => '你好',
];
- 键名（如
welcome）不能含空格或特殊字符，否则i18n('welcome')查不到 - 值支持简单占位符，但 Webman 原生不处理
%s或{name}—— 需手动sprintf(i18n('hello'), $name) - 嵌套数组（如
['auth' => ['login' => '登录']]）不被原生i18n()支持，会返回整个数组，不是字符串
语言切换后页面没变：别只改 Session，得重初始化 i18n 上下文
很多人以为只要 $_SESSION['locale'] = 'en_US'; 再跳转，i18n() 就自动切语言了。实际上 Webman 的 i18n() 是单次请求内缓存的，不会监听 Session 变更。
正确做法是在每次请求入口（如中间件或控制器基类的 initialize()）中显式调用初始化逻辑：
- 从 URL 参数（
lang=en_US）、Cookie 或 Session 中读取目标 locale - 用该 locale 调用
Webman\I18n::setLocale($locale)（注意不是setlocale()系统函数） - 确保该操作发生在任何
i18n()调用之前，否则仍用旧 locale 缓存 - 如果用了自定义中间件做语言检测，记得在
handle()里调用Webman\I18n::setLocale()，而不是只存 Session
前端也需要同步语言：别漏掉 lang 属性和 JS 共享翻译
Webman 的 i18n() 只作用于 PHP 层，HTML 的 <html lang="zh-CN"> 和前端 JS 的翻译是独立的。SEO 和可访问性都要求这两者对齐。
- 模板中必须动态设置
<html lang="{{ $locale ?? 'zh-CN' }}">，不能写死 - 若前端用 Vue/React，需通过接口或内联脚本把当前语言的翻译数组吐给 JS，例如：
window.translations = = json_encode($langArray) ?>; - 避免在 JS 里重复写
zh: { welcome: '欢迎' }—— 应复用 PHP 加载的同一份数据，否则维护两套容易不同步 - hreflang 标签必须由后端生成，不能靠 JS 插入，搜索引擎不执行 JS
i18n() 都静默失效，连 warning 都没有。 
