i18next/react-i18next 中 TypeScript 类型推断为 never 的解决方案

在 i18next/react-i18next 项目中，开发者可能会遇到一个令人困惑的类型问题：当使用 t() 函数进行翻译时，返回类型被推断为 never，而不是预期的 string 类型。这种情况通常发生在 TypeScript 环境下，特别是当项目配置与类型系统预期不符时。

问题现象

开发者在使用 t() 函数获取翻译文本时，例如：

const translatedValue = t("table.rowexpansion.collapse")

TypeScript 会将 translatedValue 的类型推断为 never，而不是预期的 string 类型。这意味着类型系统无法正确识别翻译键与返回类型之间的关系。

问题根源

经过深入分析，这个问题主要源于 i18next 的类型系统中 keySeparator 的配置。在 TypeScript 类型定义中，i18next 会使用 keySeparator 来解析嵌套的翻译键。默认情况下，keySeparator 被设置为点号(.)，这意味着类型系统会尝试将包含点号的键名解析为嵌套结构。

当开发者实际上使用的是扁平的翻译结构（即没有真正的嵌套），但键名中又包含点号时，类型系统会错误地尝试解析这些点号作为嵌套分隔符，最终导致类型推断失败，返回 never 类型。

解决方案

要解决这个问题，开发者需要在 TypeScript 的类型声明中明确指定 keySeparator 为 false。这会告诉类型系统不要尝试解析键名中的点号作为嵌套分隔符。

具体实现方式是在项目的类型声明文件中（通常是 react-i18next.d.ts 或类似文件）进行如下配置：

import 'i18next'

declare module 'i18next' {
  interface CustomTypeOptions {
    keySeparator: false
  }
}

深入理解类型系统行为

i18next 的类型系统内部使用了一个复杂的条件类型 ParseTReturn 来处理翻译键的解析。当 keySeparator 设置为默认值（点号）时，类型系统会尝试将键名分割为多个部分：

Key extends `${infer K1}${_KeySeparator}${infer RestKey}`
    ? ParseTReturn<RestKey, Res[K1 & keyof Res], TOpt>
    : // 其他处理逻辑

对于扁平结构的翻译文件，这种解析会导致 Res[K1 & keyof Res] 最终变为 never 类型，因为系统找不到对应的嵌套结构。当类型系统遇到 never 类型时，它会短路并直接返回 never，而不是继续执行其他分支逻辑。

最佳实践建议

1. 明确项目结构：在项目初期就应该明确翻译文件是采用嵌套结构还是扁平结构。

2. 类型安全配置：始终确保 TypeScript 类型配置与实际项目结构一致。如果使用扁平结构，务必设置 keySeparator: false。

3. 统一命名规范：即使使用扁平结构，也应避免在键名中使用点号，以防止潜在的混淆。

4. 类型检查：定期检查 t() 函数的返回类型，确保类型推断符合预期。

通过理解 i18next 类型系统的工作原理并正确配置项目，开发者可以避免 never 类型的问题，同时获得更好的类型安全性和开发体验。