设计系统组件i18next翻译失效问题及本地化实现问询

我基于Storybook、React、TypeScript和Material UI v5构建了一个以库形式打包的设计系统，自带i18next管理的翻译资源。宿主应用采用相同技术栈，同样用i18next处理翻译，但导入设计系统组件后，组件内的翻译仅显示键名，无法正常渲染；宿主自身翻译完全正常，手动导入设计系统翻译资源到宿主中使用也能正常工作，唯独封装的设计系统组件存在问题。

代码示例 #

设计系统i18n配置

import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import enTranslation from "./locales/en.json";
import deTranslation from "./locales/de.json";

const resources = {
  en: {
    translation: enTranslation,
  },
  de: {
    translation: deTranslation,
  },
};

i18n.use(initReactI18next).init({
  resources,
  lng: "en",
  fallbackLng: "en",
  interpolation: {
    escapeValue: false,
  },
});

export default i18n;

设计系统组件

import { useTranslation } from "react-i18next";

const DesignSystemComponent = () => {
  const { t } = useTranslation();

  return <div>{t('design_system.translation.key')}</div>;
};

export default DesignSystemComponent;

宿主应用i18n配置

import i18n from "i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import { initReactI18next } from "react-i18next";
import en from "./localization/locales/en/en.json";
import de from "./localization/locales/de/de.json";

const detectionOptions = {
  order: ["htmlTag"],
};

export type SupportedLanguage = "en" | "de";
const fallbackLng: SupportedLanguage = "en";

i18n
  .use(initReactI18next)
  .use(LanguageDetector)
  .init({
    resources: {
      en: { translation: en },
      de: { translation: de },
    },
    fallbackLng,
    debug: false,
    interpolation: {
      escapeValue: false,
    },
    detection: detectionOptions,
  });

export default i18n;

宿主应用组件

import { useTranslation } from "react-i18next";
import { DesignSystemComponent } from "design-system";

const HostAppComponent = () => {
  const { t } = useTranslation();
  
  return(
    <>
      <div>{t('host_app.translation.key')}</div> {/* 翻译正常 */}
      <DesignSystemComponent/> {/* 仅显示翻译键 */}
    </>
  );
};

export default HostAppComponent;

问题核心是设计系统和宿主各维护了独立的i18n实例，组件调用的是设计系统内部的实例，而该实例未同步宿主的语言配置和资源加载状态。以下两种方案可解决问题：

方案1：设计系统复用宿主i18n实例 #

让设计系统放弃独立初始化i18n，改为暴露翻译资源，由宿主统一整合管理，避免多实例冲突。

实现步骤 #

1. 设计系统暴露翻译资源

// 设计系统/src/i18n/resources.ts
import enTranslation from "./locales/en.json";
import deTranslation from "./locales/de.json";

// 用命名空间区分设计系统与宿主的翻译，避免键名冲突
export const designSystemResources = {
  en: {
    designSystem: enTranslation,
  },
  de: {
    designSystem: deTranslation,
  },
};

2. 设计系统组件指定命名空间

import { useTranslation } from "react-i18next";

const DesignSystemComponent = () => {
  // 明确使用designSystem命名空间
  const { t } = useTranslation('designSystem');

  return <div>{t('translation.key')}</div>;
};

3. 宿主整合设计系统资源

// 宿主i18n配置文件
import i18n from "i18next";
import LanguageDetector from "i18next-browser-languagedetector";
import { initReactI18next } from "react-i18next";
import en from "./localization/locales/en/en.json";
import de from "./localization/locales/de/de.json";
import { designSystemResources } from "design-system";

const detectionOptions = {
  order: ["htmlTag"],
};

export type SupportedLanguage = "en" | "de";
const fallbackLng: SupportedLanguage = "en";

// 合并宿主与设计系统的翻译资源
const mergedResources = {
  en: {
    translation: en,
    ...designSystemResources.en,
  },
  de: {
    translation: de,
    ...designSystemResources.de,
  },
};

i18n
  .use(initReactI18next)
  .use(LanguageDetector)
  .init({
    resources: mergedResources,
    fallbackLng,
    debug: false,
    interpolation: {
      escapeValue: false,
    },
    detection: detectionOptions,
    ns: ['translation', 'designSystem'], // 声明使用的命名空间
    defaultNS: 'translation',
  });

export default i18n;

方案2：设计系统独立兼容宿主环境 #

保留设计系统的独立i18n初始化（用于Storybook等独立场景），同时检测宿主环境并自动同步资源与配置。

实现步骤 #

1. 修改设计系统i18n配置

// 设计系统/src/i18n/index.ts
import i18n from "i18next";
import { initReactI18next, useTranslation as useTranslationBase } from "react-i18next";
import enTranslation from "./locales/en.json";
import deTranslation from "./locales/de.json";

const resources = {
  en: {
    designSystem: enTranslation,
  },
  de: {
    designSystem: deTranslation,
  },
};

// 检查宿主是否已初始化i18n实例
const hasExistingI18n = !!i18n.isInitialized;

if (!hasExistingI18n) {
  // 独立环境（如Storybook）初始化自身实例
  i18n.use(initReactI18next).init({
    resources,
    lng: "en",
    fallbackLng: "en",
    interpolation: {
      escapeValue: false,
    },
    ns: ['designSystem'],
    defaultNS: 'designSystem',
  });
} else {
  // 宿主已初始化，添加设计系统资源并加载命名空间
  i18n.addResources('en', 'designSystem', resources.en.designSystem);
  i18n.addResources('de', 'designSystem', resources.de.designSystem);
  i18n.loadNamespaces('designSystem');
}

// 封装useTranslation钩子，默认使用designSystem命名空间
export const useTranslation = () => useTranslationBase('designSystem');

2. 设计系统组件使用封装的钩子

import { useTranslation } from './i18n'; // 导入设计系统封装的钩子

const DesignSystemComponent = () => {
  const { t } = useTranslation();

  return <div>{t('translation.key')}</div>;
};

• 必须使用命名空间区分设计系统与宿主的翻译键，避免键名冲突导致翻译失效。
• 确保设计系统与宿主的i18next、react-i18next版本兼容，避免实例API不一致问题。
• 若采用方案2，宿主动态切换语言时，i18next会自动触发组件重新渲染，无需额外处理同步逻辑。

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