React-i18next useTranslation Hook多命名空间自动补全失效问题

问题根源 #

你的配置核心问题在于类型声明结构不匹配i18next的类型要求，导致TypeScript无法识别多命名空间的键：

1. 手动生成的resources.d.ts结构错误，i18next要求resources类型是「语言 -> 命名空间 -> 翻译键」的层级，而非直接将命名空间作为顶层键
2. i18next.d.ts中ns使用了数组类型，而非i18next需要的命名空间联合类型

修复步骤 #

1. 优化i18n.ts，导出正确的命名空间联合类型 #

修改i18n.ts，添加命名空间的联合类型导出，同时确保ns是只读数组：

import i18n from "i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import { initReactI18next } from "react-i18next";

import TIMESHEET_DE from "@/locales/de/timesheet.json";
import TRANSLATION_DE from "@/locales/de/translation.json";
import TIMESHEET_EN from "@/locales/en/timesheet.json";
import TRANSLATION_EN from "@/locales/en/translation.json";
import TIMESHEET_FR from "@/locales/fr/timesheet.json";
import TRANSLATION_FR from "@/locales/fr/translation.json";
import TIMESHEET_IT from "@/locales/it/timesheet.json";
import TRANSLATION_IT from "@/locales/it/translation.json";

const resources = {
  en: {
    translation: TRANSLATION_EN,
    timesheet: TIMESHEET_EN,
  },
  fr: {
    translation: TRANSLATION_FR,
    timesheet: TIMESHEET_FR,
  },
  it: {
    translation: TRANSLATION_IT,
    timesheet: TIMESHEET_IT,
  },
  de: {
    translation: TRANSLATION_DE,
    timesheet: TIMESHEET_DE,
  },
} as const;

const defaultNS = "translation";
const ns = ["translation", "timesheet"] as const;
export type NS = typeof ns[number]; // 导出命名空间联合类型

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    returnEmptyString: false,
    debug: import.meta.env.DEV,
    fallbackLng: "en",
    lng: "en",
    defaultNS,
    ns,
    interpolation: {
      escapeValue: false,
    },
    resources: resources,
  });

export default i18n;
export { defaultNS, ns, resources };

2. 修正i18next.d.ts的类型声明 #

直接从i18n.ts导入推导好的类型，替换错误的resources和ns类型：

import type { resources, defaultNS, NS } from "@/i18n";

declare module "i18next" {
  interface CustomTypeOptions {
    resources: typeof resources; // 直接使用i18n.ts中推导的resources类型
    defaultNS: typeof defaultNS;
    ns: NS; // 使用命名空间联合类型而非数组类型
  }
}

3. 移除冗余的resources.d.ts #

现在类型直接从i18n.ts的resources常量推导，无需手动维护resources.d.ts，可以直接删除该文件。

验证效果 #

修改完成后：

• 调用t("common.Case")（默认命名空间）可正常触发自动补全
• 调用t("timesheet:placeholder.What are you working on")不会再出现TS错误，且支持补全
• 切换defaultNS时，其他命名空间仍可通过ns:key格式正常访问

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