Yii框架多语言获取技巧

本文深入解析了Yii框架在RESTful API场景下实现多语言支持的关键技巧与常见陷阱，强调必须在控制器的beforeAction()中显式、安全地从Accept-Language头、lang参数或用户档案提取并校验语言标识，及时设置Yii::$app->language及i18n组件语言，同时确保intl扩展启用、翻译文件路径与category严格匹配、Formatter locale正确同步——任何环节疏漏都会导致Yii::t()、验证错误、日期数字格式等仍以默认语言渲染，而这些问题往往因REST接口绕过视图层而被隐蔽放大。

RESTful 接口本身不自动读取或设置 Yii::$app->language，必须显式从请求中提取语言标识并手动赋值，否则 Yii::t()、Formatter（如日期/数字格式）、验证器错误信息等仍按默认语言渲染。

怎么从 REST 请求里安全提取 language 值

REST 接口通常不走前端路由规则，也不依赖美化 URL 的路径段（如 /zh-CN/v1/users），所以不能靠 UrlManager 解析首段。常见可靠来源只有三个：HTTP 头 Accept-Language、请求参数（?lang=ja-JP）、或认证后用户 profile 字段。

• Accept-Language 是最标准的依据，但需解析优先级和匹配精度（如 zh-CN;q=0.9, zh;q=0.8），建议用 yii\helpers\StringHelper::basename() 或正则粗筛主语言码，避免直接信任完整值
• 显式 lang 参数仅在调试或客户端强控时使用，上线后应校验其是否在白名单内（如 ['en-US', 'zh-CN', 'ja-JP']），防止任意字符串污染 Yii::$app->language
• 若接口已鉴权且用户表存有 preferred_language 字段，应以该字段为准，它比请求头更符合用户真实偏好
• 绝不要 fallback 到 $_SERVER['HTTP_ACCEPT_LANGUAGE'] 原始字符串——未解析时可能含空格、非法字符，直接赋值会导致 Formatter 初始化失败或静默降级

在哪里设置 Yii::$app->language 才有效

必须在控制器动作执行前完成赋值，否则 Validator、ActiveRecord::scenarios()、Formatter 初始化都已完成，再改 language 也无效。REST 场景下，beforeAction() 是唯一合理位置，但要注意它对所有动作生效，需排除 OPTIONS 预检请求。

• 在基控制器（如 ActiveController 子类）重写 beforeAction()，先调用 parent::beforeAction($action)，再提取并设置语言
• 跳过 $action->id === 'options'，避免预检请求触发无意义的语言初始化
• 设置后立即调用 Yii::$app->i18n->setLanguage(Yii::$app->language)，确保翻译组件同步更新（尤其当 i18n 组件被延迟加载时）
• 不要在 init() 里设——此时 Request 对象可能还未完全绑定，get() 或 getHeaders() 可能返回空

为什么 Yii::t() 在 API 返回里还是英文

常见原因是翻译文件没加载或 category 不匹配，而非语言设置失败。REST 接口常忽略视图层，容易漏掉 i18n 组件配置或消息源路径错误。

• 检查 config/web.php 中 i18n 组件是否注册，且 sourceLanguage 明确设为 'en-US'（别用 zh-CN 作源语言，否则翻译逻辑反转）
• 确认翻译文件路径正确：@app/messages/zh-CN/app.php 对应 Yii::t('app', 'Save')，category 名必须与文件名一致，大小写敏感
• 运行 ./yii message/extract 后，清空 runtime/i18n 缓存目录——缓存会记住旧的 category 映射，改了文件也不生效
• 如果用 JsonResponseFormatter，确保它不干扰 Yii::t() 调用；错误信息来自模型验证时，要检查 ActiveRecord::attributeLabels() 是否也用了 Yii::t()

Formatter 日期/数字格式没随 language 变

Formatter 依赖 ICU 数据库驱动本地化格式，光设 Yii::$app->language 不够，还必须确保 PHP 启用了 intl 扩展，且 ICU 版本支持目标语言。

• 执行 php -m | grep intl 确认扩展已启用；若无输出，需安装 php-intl 并重启 Web 服务
• 检查 Yii::$app->formatter->locale 是否等于 Yii::$app->language，默认情况下它会自动同步，但若你在某处手动设过 formatter->locale，就会覆盖自动同步
• ICU 不支持某些小众 locale（如 zh-Hans），应优先使用标准码如 zh-CN；可用 Locale::acceptFromHttp() 测试是否被 ICU 识别
• API 返回 JSON 时，DateTime 对象经 JsonSerializer 处理，其格式由 formatter->datetimeFormat 控制，这个属性是字符串模板，不是 locale——真正起作用的是 formatter->locale 和底层 ICU

最易被忽略的一点：REST 接口常绕过 View 组件，导致 Formatter 的 locale 初始化时机错乱。如果你在 beforeAction() 里设置了 language，但没显式触发 Yii::$app->formatter->init()，部分格式方法（尤其是首次调用）可能仍用默认 locale。这不是 bug，而是 Yii 的 lazy-init 设计使然。

到这里，我们也就讲完了《Yii框架多语言获取技巧》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Yii框架的知识点！