如何让i18next的t()函数仅返回字符串以解决TypeScript类型错误？

问题背景 #

i18next v22.0.0为翻译函数t()添加了完整的类型安全特性，但由于t()支持获取嵌套翻译对象，它的返回类型会是string | 对象类型。当你明确传入的翻译键只会返回字符串，且需要在必须返回字符串的场景中使用t()时，就会出现TypeScript类型不匹配的错误，比如以下代码：

const resources = {
  en: {
    translation: {
      world:  {
        withGreeting: 'Hello World',
        withoutGreeting: 'World',
        someNestedProperty: {
          hello: 'Text',
        }
      },
    },
  },
}

// 声明i18next类型
declare module "i18next" {
  interface CustomTypeOptions {
    resources: typeof resources["en"];
  }
}

// 初始化i18next（省略）

const getText = (enabled: boolean): string => {
   if(enabled) {
     // TypeScript错误：string | { hello: string } 无法赋值给string类型
     return t('world.withGreeting');  
   }
   return t('world.withoutGreeting');
}

解决方案 #

方法一：自定义类型安全的翻译函数 #

创建一个封装函数，仅接受会返回字符串的翻译键，并强制返回字符串类型，同时保留i18next的类型校验：

import i18n from 'i18next';

// 定义仅返回字符串的翻译键类型
type StringTranslationKeys = {
  [K in keyof typeof resources["en"]["translation"]]: 
    typeof resources["en"]["translation"][K] extends string ? K : 
    typeof resources["en"]["translation"][K] extends object ? 
      { [NK in keyof typeof resources["en"]["translation"][K]]: 
        typeof resources["en"]["translation"][K][NK] extends string ? `${K}.${NK}` : never 
      }[keyof typeof resources["en"]["translation"][K]] : never
}[keyof typeof resources["en"]["translation"]];

// 封装翻译函数
const tString = (key: StringTranslationKeys): string => {
  return i18n.t(key) as string;
};

// 使用示例
const getText = (enabled: boolean): string => {
   if(enabled) {
     return tString('world.withGreeting'); // 无类型错误
   }
   return tString('world.withoutGreeting'); // 无类型错误
};

这个方法既保留了类型安全（只能传入返回字符串的键），又强制返回字符串，避免了手动断言的繁琐。

方法二：局部类型断言（快速解决方案） #

如果只是个别场景需要，可以直接使用类型断言，明确告诉TypeScript当前调用返回的是字符串：

const getText = (enabled: boolean): string => {
   if(enabled) {
     return t('world.withGreeting') as string;  
   }
   return t('world.withoutGreeting') as string;
}

这种方法简单直接，但缺点是如果后续翻译键对应的类型改变（比如改成对象），TypeScript不会给出警告，存在一定维护风险。

方法三：扩展i18next的TFunction类型（全局修改） #

如果你整个项目都只需要t()返回字符串，可以通过模块扩展重定义TFunction的返回类型：

declare module "i18next" {
  interface CustomTypeOptions {
    resources: typeof resources["en"];
  }

  // 重写TFunction的返回类型为string
  interface TFunction {
    <TResult extends string = string>(key: Key, options?: TOptions): TResult;
  }
}

注意：这种方法会全局修改t()的返回类型，如果你有需要获取嵌套对象的场景，不建议使用。

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