乐闻世界logo
6月1日 02:21

i18next 常见坑有哪些？翻译不显示/切换失效/插值失败排查指南

i18next 是前端最流行的国际化框架，使用中常遇到的问题按频率排列：翻译不显示多数是因为资源未加载完毕就渲染了组件、命名空间拼写错误、或语言代码格式不一致（zh vs zh-CN）；语言切换不生效通常是组件未正确监听语言变化或 React 未触发重渲染；插值失败多半是 interpolation 配置缺失或变量名拼写不对；复数处理异常则是未配置对应语言的复数规则。性能方面，一次性加载所有语言资源会导致首屏变慢，应改为按需加载加缓存。缺失翻译可通过 fallbackLng 和 saveMissing 兜底。SSR 场景（如 Next.js）需注意服务端和客户端实例隔离。调试最直接的方式是开启 debug: true。

追问

翻译 key 存在但页面显示 key 原文？

检查三点：资源文件是否在组件渲染前加载完成，可用 useTranslation 的 ready 状态判断；命名空间是否与 t() 调用一致；语言代码是否匹配，i18next 默认区分大小写，zh-CN 和 zh_cn 是不同 key。

js
const { t, ready } = useTranslation('common');
if (!ready) return <Loading />;

语言切换后组件不更新？

确保使用的是框架绑定库（如 react-i18next）提供的 useTranslation 或 withTranslation，而非直接调用 i18next.t()。后者是同步快照，不会响应语言变化。另外检查 initImmediate 是否设为 true，否则资源加载可能是异步的但切换时未等待完成。

插值变量不替换怎么办？

默认插值格式是 {{variable}}，花括号前后不能有空格。确认变量名与模板一致，同时检查 interpolation.escapeValue 配置——在 React 中应设为 false，因为 React 自身会转义。

js
// 正确
t('hello', { name: '世界' }) // "你好 {{name}}" → "你好 世界"
// 错误：花括号内有空格
"你好 {{ name }}"

复数形式不生效？

i18next 的复数基于 Unicode CLDR 规则，需要对应语言的复数后缀（如英语 _plural，俄语有更多形式）。确认资源 key 拼写正确，且 interpolation 中 skipOnVariables 未被误设。对于中文这类无复数区分的语言，直接用普通 key 即可。

json
{
  "item": "{{count}} item",
  "item_plural": "{{count}} items"
}

生产环境如何处理缺失翻译？

三步走：fallbackLng 指定回退语言；saveMissing: true 配合 missingKeyHandler 将缺失 key 上报至翻译管理平台；开发环境开启 debug: true 在控制台打印缺失警告。Next.js SSR 场景下，确保服务端和客户端各持独立的 i18next 实例，避免请求间状态污染。

标签：i18next