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生成的逻辑以及缓存清理这三个关键细节。它们通常不会产生显式错误，却足以导致整个国际化功能在关键时刻失效。
