PHP Locale::getPrimaryLanguage 提取语言标签主语言的方法

处理多语言请求时，我更愿意先把 locale 拆成可复用的字段，而不是把 zh-Hant-TW 当成一个不可解释的字符串。PHP 的 Locale::getPrimaryLanguage() 正好负责取出主语言部分：zh-Hant-TW 得到 zh，en-US 得到 en。它属于 intl 扩展，适合做界面语言选择、日志分组和内容兜底。

官方地址：https://www.php.net/manual/en/locale.getprimarylanguage.php

先确认 intl 扩展和语言标签格式

Locale API 由 PHP 的 Internationalization（intl）扩展提供，底层依赖 ICU。线上容器如果没有加载它，类方法不存在，排查方向应是运行时扩展，而不是反复修改 locale 字符串。

输入可以是带连字符的语言标签，也可以是 PHP/ICU 能接受的传统下划线形式。项目内部最好统一一种格式，并在入口处做长度、字符集和允许范围检查；方法负责提取，不等于完整的 locale 合法性校验。

用 getPrimaryLanguage 取得主语言代码

这个方法的职责很窄：从输入 locale 中取出语言代码。它不会替你选择翻译资源，也不会把 zh 自动扩展成简体或繁体。实际项目里，主语言通常用于第一层路由，后续再根据脚本和地区做更细的匹配。

 %s%s", $locale, $language ?? '未知', PHP_EOL);
}

如果只需要按语言加载基础文案，取出的代码就够用；如果要区分繁体中文、台湾地区英语或加拿大法语，就不要丢掉原始标签。

把主语言、脚本和地区拆开处理

同一个 locale 可能同时包含语言、脚本和地区。PHP 提供了对应的静态方法，组合起来比手写 explode('-') 更稳妥，因为脚本和地区的位置、大小写并不应由业务代码猜测。

 Locale::getPrimaryLanguage($locale),
    'script' => Locale::getScript($locale),
    'region' => Locale::getRegion($locale),
];

var_export($parts); // language=zh，script=Hant，region=TW

处理空值、超长输入和 PHP 版本边界

getPrimaryLanguage() 的返回类型是 ?string。没有可取出的语言部分，或输入超过 INTL_MAX_LOCALE_LEN 时，结果可能是 null。因此调用方要先判断结果，再决定采用默认语言；不要把空字符串直接当成中文或英语。

另外，PHP 8.5 起，Locale 方法收到包含 null 字节的参数会抛出 ValueError。来自请求头或数据库的值应先做边界检查，并在应用层记录原始输入的摘要，而不是把未经处理的控制字符继续传入 ICU。

• 需要一个语言代码：使用 getPrimaryLanguage。
• 需要同时取多个子标签：使用 parseLocale 或组合 getScript、getRegion。
• 需要语言协商：另行设计候选列表和回退顺序，不把本方法当成匹配器。

常见问题

没有安装 intl 时能否用字符串截取替代？

临时脚本可以做简单拆分，但生产代码容易误判脚本、地区和传统格式。优先安装并加载 intl，再让 Locale API 处理子标签。

返回的 zh 能直接决定简体还是繁体吗？

不能。简繁通常需要结合 getScript、地区或产品自己的语言资源策略，主语言只提供第一层分类。

什么时候应该用 parseLocale？

当页面需要一次取得多个子标签，或要把 locale 拆成字段保存时，parseLocale 更合适；只取主语言时，直接调用 getPrimaryLanguage 更清晰。