Yii框架多语言切换教程 i18n配置步骤详解

Yii多语言切换必须在应用初始化早期设置language，否则组件已按默认语言初始化；需在web/index.php中new Application后、run()前赋值，或在bootstrap阶段处理URL前缀；Url::to()不自动补语言段，须显式传lang参数并清缓存。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

为Yii应用添加多语言支持，是许多开发者面临的挑战。不少人误以为只需修改language配置即可，却发现页面内容毫无变化。问题的核心在于时机——语言设置必须在Yii应用初始化的早期阶段完成。一旦视图组件、验证器、日期格式器等核心服务按照默认语言初始化完毕，后续的任何配置更改都将失效。

Yii::$app->language 必须在 Application::init() 前设置

一个常见的错误是将语言切换逻辑放置在Controller::beforeAction()或某个actionLanguage()方法中。此时为时已晚，Yii::t()可能已读取缓存，Formatter也已加载了旧语言的ICU数据，导致界面无法更新，甚至数字和日期格式错乱。

• 最可靠的位置是入口文件web/index.php。在new yii\web\Application($config)实例化之后，立即调用->run()方法之前，就确定应用语言。
• 另一种方案是在bootstrap阶段（例如通过自定义引导类）处理。从Yii::$app->request->getPathInfo()中解析URL前缀的语言代码（例如/zh-CN/site/index中的zh-CN），验证其有效性后进行设置。
• 需特别注意：避免依赖$_GET[‘lang’]参数，当启用URL美化时，该参数可能为空。也不要在UrlRule子类中修改language，因为URL规则匹配发生在语言初始化之后，无法生效。

URL 路由带语言前缀时，Url::to() 不会自动补 lang 段

这是另一个高频陷阱。默认情况下，Url::to([‘site/about’])仅依据定义的路由规则生成URL，它不会自动关联当前的语言上下文。导致用户刚切换到ja-JP语言，点击内部链接后却跳转回en-US页面。

• 因此，所有内部链接生成都必须显式传递语言参数：Url::to([‘site/about’, ‘lang’ => Yii::$app->language])。
• 若项目中大量使用Url::to()，建议封装一个LangUrl::to()辅助方法，默认自动注入当前的Yii::$app->language值，提升开发效率。
• 此外，生成语言切换链接时需避免前缀嵌套。例如从/zh-CN/site/index切换至英文，目标地址应为/en-US/site/index，而非/en-US/zh-CN/site/index。正确做法是使用explode(‘/‘, $path)剥离URL中已有的语言前缀，再拼接新的前缀。

翻译文件路径和命名必须严格匹配 PhpMessageSource 规则

Yii::t(‘app’, ‘Home’)能否成功获取翻译，取决于一系列严格的规则匹配：sourceLanguage、basePath、目录结构、文件名及数组键名必须完全对应。任何一处不匹配都会导致静默失败，既不报错也不显示翻译，增加排查难度。

• basePath必须指向真实存在且可读的目录，例如@app/messages对应./messages/。
• 语言子目录的名称必须使用标准语言代码，如zh-CN、en-US。使用zh_cn或简写zh将无法识别。
• 分类名（如app）直接对应文件名（app.php），文件内部必须是return [‘Home’ => ‘首页’];这样的数组格式。注意键名大小写敏感，‘home’与‘Home’被视为不同词条。
• 若配置中使用了通配符规则‘*’，务必在fileMap中显式声明每个分类的映射关系，否则PhpMessageSource将无法定位文件，直接返回原文。

动态切换语言后，必须同步持久化并清 runtime 缓存

仅修改Yii::$app->language运行时变量是临时的，页面刷新后即恢复默认。更复杂的是，PhpMessageSource默认会缓存翻译结果，若切换语言后未清理缓存，用户看到的仍是旧内容。

• 用户选择的语言值，建议存入session：Yii::$app->session[‘language’] = $lang;，并在应用入口处读取该值来设置语言。
• 执行语言切换操作后，务必调用Yii::$app->i18n->translator->flush();清空翻译缓存。或直接手动删除runtime/messages/目录下对应的语言文件夹。
• 最后需注意，sourceLanguage（源代码语言）应固定为en-US（或你编写代码时使用的原始语言），切勿让其随用户语言动态变化。否则Yii::t()的匹配逻辑将出现混乱。

综上所述，Yii多语言实现的难点往往不在于翻译文件的编写，而在于语言设置的时机、URL生成的逻辑以及缓存清理这三个关键细节。它们通常不会产生显式错误，却足以导致整个国际化功能在关键时刻失效。