如何利用Composer集成 PHP-Gettext 库实现基于 .mo 文件的多语言支持-composer-PHP中文网

php原生gettext扩展不可被php-gettext composer包替代，后者仅为兼容层；真正高效加载.mo文件必须启用php_gettext.so/.dll扩展，并严格遵循locale/zh_cn/lc_messages/messages.mo路径结构。

如何利用composer集成 php-gettext 库实现基于 .mo 文件的多语言支持

php-gettext Composer 包不能替代 PHP 原生 gettext 扩展

直接装 php-gettext Composer 包（如 php-gettext/php-gettext）并不能让你用上真正的 gettext() 函数——它只是个纯 PHP 实现的兼容层，不依赖系统 locale，也不支持 .mo 文件的二进制高效加载。你调用 gettext() 时实际走的是它的模拟逻辑，性能差、不识别复数规则、无法绑定 LC_MESSAGES 子目录结构，且和原生扩展行为不一致。

真正读取编译后的 messages.mo 并高速匹配字符串，必须启用 PHP 自带的 gettext 扩展（即 php_gettext.dll 或 gettext.so）。Composer 包只适合：没有服务器权限、无法启用扩展、或仅需极简 fallback 场景。

检查是否已启用原生扩展：extension_loaded('gettext') 返回 true，且 phpinfo() 中有 “gettext” 模块段落
php-gettext/php-gettext 包的 gettext_reader 类只能手动加载单个 .mo 文件，不支持 bindtextdomain() 和语言域自动切换
若强行用 Composer 包代替原生扩展，_()、ngettext()、pgettext() 全部失效，必须改写为 $reader->gettext() 调用方式

正确路径：先启用 PHP 原生 gettext，再用 Composer 管理工具链

Composer 的价值不在运行时翻译，而在构建期——帮你自动化提取、合并、校验 .po 文件。推荐组合：gettext 扩展（运行时） + symfony/translation 或 php-gettext/gettext（开发期工具）。

php-gettext/gettext 是 GNU gettext 工具的 PHP 实现（含 xgettext、msgfmt、msgmerge 等命令），可替代系统级 gettext 工具链，避免在 Windows 或无 sudo 权限环境里折腾编译器。

安装工具包：composer require php-gettext/gettext --dev
提取源字符串：vendor/bin/xgettext --from-code=UTF-8 -o locales/messages.pot src/*.php
合并更新翻译：vendor/bin/msgmerge locales/zh_CN/messages.po locales/messages.pot -o locales/zh_CN/messages.po
编译为 .mo：vendor/bin/msgfmt locales/zh_CN/messages.po -o locales/zh_CN/LC_MESSAGES/messages.mo
注意：生成的 .mo 文件路径结构必须严格匹配 bindtextdomain() 设置，例如 locales/zh_CN/LC_MESSAGES/messages.mo

bindtextdomain() 路径必须真实存在且可读

PHP 原生 gettext 扩展不会报错提示“找不到 .mo”，而是静默回退到原文。常见原因是路径拼写错误、权限不足，或没创建 LC_MESSAGES 子目录。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

假设你调用 bindtextdomain('messages', './locales')，那么实际查找路径是：./locales/zh_CN/LC_MESSAGES/messages.mo（不是 ./locales/zh_CN/messages.mo）。少一层 LC_MESSAGES 就失败。

Windows 下路径分隔符无关紧要，但目录名大小写敏感：必须是 LC_MESSAGES，不能写成 lc_messages 或 Lc_Messages
setlocale(LC_ALL, 'zh_CN.UTF-8') 中的 locale 名必须被系统支持；Windows 常用 Chinese_China.936 或 zh_CN，Linux 用 zh_CN.UTF-8；可用 setlocale(LC_ALL, 'zh_CN', 'zh', 'Chinese') 多备选
测试是否生效：var_dump(gettext('nonexistent-string')) —— 若返回原文，说明 .mo 未加载；若返回空字符串，说明 locale 不匹配或文件损坏

$_GET['lang'] 切换时 setlocale() 必须重设

PHP 的 setlocale() 是进程级状态，不是会话级。每次请求都得重新设置，不能靠一次配置全局生效。

别写成“初始化一次就完事”，尤其在 FastCGI 或 PHP-FPM 环境下，worker 进程会复用，旧 locale 可能残留。

典型错误写法：if (!isset($_SESSION['lang'])) { setlocale(LC_ALL, $_GET['lang'].'.UTF-8'); } —— 缺少 fallback 和验证
安全做法：从白名单取值，强制加 .UTF-8 后缀，并验证返回值：$lang = in_array($_GET['lang'], ['en_US', 'zh_CN']) ? $_GET['lang'] : 'en_US'; $ret = setlocale(LC_ALL, $lang.'.UTF-8', $lang); if (!$ret) { error_log("setlocale failed for $lang"); }
绑定 domain 和设置 textdomain() 也必须在每次请求中执行，不能只在入口文件开头做一次

真正卡住人的从来不是函数怎么写，而是 LC_MESSAGES 目录少建了一层、Windows locale 名写错了、或者以为 Composer 包能代替 extension=gettext —— 这些地方一错，_() 就永远返回原文，还查不出错在哪里。