phpEnv中gettext需源码编译支持并配置系统locale：检查ext/gettext存在、安装gettext开发包、重装PHP；生成zh_CN.UTF-8等locale；bindtextdomain用绝对路径；setlocale需fallback且动态设置。
phpEnv 默认不启用 gettext 扩展，必须手动开启并配合系统 locale 支持才能让多语言生效。光改 php.ini 不够，常见失败都是卡在系统级 locale 缺失或路径配置错。
确认 phpEnv 中的 PHP 是否已编译支持 gettext
phpEnv 是基于源码编译的 PHP 环境管理工具，它不会自动启用所有扩展。gettext 需要编译时链接系统 libgettext，否则即使加了 extension=gettext 也会报“undefined function gettext()”。
- 进入你的 phpEnv 对应 PHP 版本源码目录（如
~/.phpenv/versions/8.2.12/src），检查是否存在ext/gettext/子目录 - 运行
php -m | grep gettext；若无输出，说明未编译进 PHP - 重新编译需确保系统已安装开发包：
sudo apt install gettext-devel（CentOS/RHEL）或sudo apt install gettext-base libgettextpo-dev（Ubuntu/Debian） - 然后用 phpEnv 重装该版本：
phpenv install 8.2.12 --reinstall（会触发完整编译流程）
启用扩展后仍报错“Failed to set locale”
phpEnv 下的 PHP 进程默认继承 shell locale，但很多最小化系统（如 Ubuntu Server）只预装 C.UTF-8，没有 zh_CN.UTF-8 或 en_US.UTF-8。gettext 的 setlocale(LC_ALL, 'zh_CN.UTF-8') 会静默失败，后续 _() 全部返回原文。
- 运行
locale -a | grep -E "zh_CN|en_US"，若无结果，需生成 locale：sudo locale-gen zh_CN.UTF-8 en_US.UTF-8 - 在 phpEnv 启动脚本（如 Apache 的 envvars 或 PHP-FPM pool 配置）中显式设置环境变量：
export LANG=zh_CN.UTF-8和export LC_ALL=zh_CN.UTF-8 - PHP 脚本里不要只写
setlocale(LC_ALL, 'zh_CN.UTF-8')，应提供 fallback：setlocale(LC_ALL, 'zh_CN.UTF-8', 'zh_CN', 'C.UTF-8')
bindtextdomain 路径不对导致 _() 始终返回英文
phpEnv 本身不干预文件路径，但开发者常把 locale/ 目录放在 webroot 下却没注意 bindtextdomain 的第二个参数是「根目录」，不是 .mo 文件的完整路径。
立即学习“PHP免费学习笔记（深入）”；
- 正确结构应为：
./locale/zh_CN/LC_MESSAGES/messages.mo，调用时写bindtextdomain('messages', './locale') - 若项目在子目录（如
/var/www/myapp），./locale是相对当前工作目录的——而 CLI 和 Web SAPI 的工作目录可能不同，建议用绝对路径：bindtextdomain('messages', __DIR__ . '/locale') - 检查
messages.mo文件权限：Web 服务器用户（如 www-data）必须有读取权限，且文件不能是空的（可用file locale/zh_CN/LC_MESSAGES/messages.mo验证是否为 valid GNU message catalog）
动态切换语言时 setlocale 失效
PHP 的 setlocale 是进程级的，在 FPM 模式下，一个 worker 进程可能服务多个请求，setlocale 修改会影响后续请求——除非你每次都在请求开头重设，且确保没被其他中间件覆盖。
- 避免在全局配置中一次性
setlocale，应在每个请求入口（如 router.php 或 index.php）顶部根据$_GET['lang']动态设置 - 用
putenv("LANG={$lang}.UTF-8")配合setlocale更可靠，尤其在 CGI/FastCGI 场景下 - 如果用了 OPcache，注意
.mo文件更新后，gettext 缓存不会自动刷新——需重启 PHP-FPM 或临时禁用 OPcache 验证逻辑
最易被忽略的一点：gettext 的语言匹配是严格按 locale 名称来的，zh-CN 和 zh_CN 是两个不同 locale，messages.mo 必须放在 zh_CN/LC_MESSAGES/ 下，不能写成 zh-CN 或 zh ——否则 bindtextdomain 找不到对应目录，就退回到默认域（通常是英文）。
