i18next无法自动推断命名空间前缀，如何修复？

问题描述 #

配置i18next的TypeScript类型定义时遇到类型推断异常，当前类型定义代码如下：

// i18next.d.ts

import 'i18next';
import translations from 'public/locales/ptBR/translation.json';

type key = typeof translations;

declare module 'i18next' {
  interface CustomTypeOptions {
    nsSeparator: '.';
    defaultNS: 'translation';
    resources: {
      translation: key;
    };
  }
}

使用typeof translations时，无嵌套的字符串键会被推断为keyof string类型。实际调用翻译函数时，例如：

{
  path: '/resume',
  label: <Translation>{t => <span>{t('resume')}</span>}</Translation>
},

必须传入translation.resume才能通过类型检查，但i18n初始化配置已将defaultNS设为'translation'，希望找到无需修改所有翻译调用的修复方法。

i18n初始化代码：

i18n
  .use(initReactI18next)
  .use(Backend)
  .init({
    backend: {
      loadPath: getTranslateFilePath()
    },
    defaultNS: 'translation',
    lng: 'ptBR',
    fallbackLng: 'ptBR',
    debug: ENV !== 'production',
    interpolation: {
      escapeValue: false
    }
  });

修复方案 #

1. 修正类型定义文件 #

调整i18next.d.ts，确保默认命名空间的键被正确推断，让t函数支持直接传入键名：

// i18next.d.ts
import 'i18next';
import translations from 'public/locales/ptBR/translation.json';

declare module 'i18next' {
  interface CustomTypeOptions {
    nsSeparator: '.';
    defaultNS: 'translation';
    // 直接使用翻译文件的类型，确保键被正确识别为字面量类型
    resources: {
      translation: typeof translations;
    };
    // 如果翻译包含嵌套键，需配置keySeparator
    keySeparator: '.';
  }
}

2. 确保TypeScript正确解析JSON模块 #

检查tsconfig.json中启用了resolveJsonModule，保证JSON文件的类型能被正确推断：

{
  "compilerOptions": {
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

3. 处理键类型被推断为keyof string的情况 #

如果JSON文件的键仍被推断为keyof string，可以使用LiteralUnion强制保留字符串字面量类型（需安装type-fest库）：

// i18next.d.ts
import 'i18next';
import translations from 'public/locales/ptBR/translation.json';
import { LiteralUnion } from 'type-fest';

// 提取翻译键并保留字面量类型
type TranslationKeys = LiteralUnion<keyof typeof translations, string>;

declare module 'i18next' {
  interface CustomTypeOptions {
    nsSeparator: '.';
    defaultNS: 'translation';
    resources: {
      translation: typeof translations;
    };
    keySeparator: '.';
    // 明确默认命名空间和键前缀，让类型检查更精准
    DefaultNamespace: 'translation';
    KeyPrefix: '';
  }
}

内容的提问来源于stack exchange，提问作者Gabriel Nadaleti