PHP国际化避坑核心是环境适配：需确认系统locale存在、setlocale()返回true、bindtextdomain路径正确，Apache/PHP-FPM需重启生效；无法控制环境时可用php-gettext替代，但需手动处理复数形式。
PHP 做国际化，别碰 gettext 的默认系统路径和二进制工具链——本地开发容易卡在 .mo 文件不生效、setlocale() 返回 false、或语言切换后字符串完全不变。
为什么 gettext 在 PHP 中常“看起来配置对了却没反应”
根本原因不是函数写错，而是环境级依赖没对齐：PHP 的 gettext 扩展只读取特定目录结构下的二进制 .mo 文件，且严重依赖系统 LC_MESSAGES 区域设置。Mac 默认没开 en_US.UTF-8 这类 locale，Docker 容器里更常是空的。
- 用
locale -a | grep 'en_US.utf8'（Linux）或locale -a | grep 'en_US.UTF-8'（Mac）确认系统是否存在目标 locale - PHP 中调用
setlocale(LC_MESSAGES, 'en_US.UTF-8')后必须检查返回值——返回false就说明系统根本不认这个 locale，后续gettext()必定静默失败 -
bindtextdomain('messages', '/path/to/locales')的第二个参数必须是包含zh_CN/LC_MESSAGES/messages.mo这种结构的父目录，不能直接指到.mo文件 - 修改完 locale 或 .mo 文件后，Apache 需要重启（PHP-FPM 则需 reload），因为
gettext会缓存 domain 句柄
绕过系统 locale 依赖：用 php-gettext 纯 PHP 实现
当无法控制服务器环境（如共享主机、某些 Docker 基础镜像），或团队不想学 msgfmt 工具链时，php-gettext 是更可控的选择。它直接读取 .po 或 .mo 文件，不调用系统 gettext C 库。
- 用 Composer 安装：
composer require php-gettext/gettext - 加载时指定完整路径：
$t = new \Gettext\Translations(); $t->loadPhpArray('/path/to/zh_CN.php');（推荐导出为 PHP 数组，比解析 .mo 更快且无扩展依赖） - 手动映射语言代码到文件路径，避免硬编码：
$lang = $_GET['lang'] ?? 'en'; $translations = include "locales/{$lang}.php"; - 注意：纯 PHP 方案不支持复数形式（plural forms）的自动选择，需自己按
n == 1 ? 'item' : 'items'分支处理
HTTP Accept-Language 不是银弹：用户语言偏好 ≠ 实际展示语言
浏览器发来的 Accept-Language: zh-CN,zh;q=0.9,en;q=0.8 只代表“支持”，不代表“想看”。真实场景中，用户可能因设备设置错误、公司网络代理改头、或单纯想切英文查资料而需要手动覆盖。
立即学习“PHP免费学习笔记（深入）”；
- 必须提供显式语言切换入口（如页脚国旗图标或下拉框），且切换后把选择存入
$_SESSION或带签名的 Cookie，优先级高于请求头 - URL 路径应体现语言，例如
/zh/about和/en/about，方便 SEO 和用户分享；可用 Nginx 重写或 PHP 路由层解析前缀 - 不要用
$_SERVER['HTTP_ACCEPT_LANGUAGE']直接决定setlocale()参数——zh-CN和系统 locale 名zh_CN.UTF-8格式不一致，需做映射表转换
真正卡住人的从来不是翻译键怎么写，而是 locale 初始化时机、.mo 文件权限（Web 用户得有读权限）、以及 Apache mod_php 和 PHP-FPM 下 gettext 缓存行为的差异。上线前务必在目标环境跑一次 var_dump(setlocale(LC_MESSAGES, 'xx_XX.UTF-8')); 和 var_dump(bindtextdomain('messages', $dir)); 确认每一步返回非 false。
