如何使用react-i18next正确翻译NX库单仓项目？

针对你在NX monorepo组件库中使用i18next的场景，绝对不要为每个组件单独包裹I18NextProvider，正确的做法是导出配置好的i18next实例，让使用者在应用根层级统一用I18NextProvider包裹，具体原因和实现方式如下：

为什么不能给每个组件套Provider #

• 每个I18NextProvider会创建独立的i18next实例，导致组件间翻译状态不一致（比如切换语言时，不同组件可能显示不同语言版本）
• 大量冗余代码，增加组件维护成本，违背组件库的复用性设计原则

正确实现方案 #

1. 在组件库中配置基础i18next实例 #

创建一个独立的i18next实例，配置好组件库所需的翻译资源、默认语言等核心参数，同时提供资源合并能力，方便使用者将库的翻译资源整合到自身已有的i18n配置中。

示例代码：

// libs/your-lib/src/lib/i18n.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
// 导入组件库的翻译文件
import enLocale from './locales/en.json';
import zhLocale from './locales/zh.json';

// 创建独立实例，避免污染全局i18n
const libI18n = i18n.createInstance();

// 初始化实例
libI18n.use(initReactI18next).init({
  resources: {
    en: { translation: enLocale },
    zh: { translation: zhLocale }
  },
  lng: 'en',
  fallbackLng: 'en',
  interpolation: {
    escapeValue: false // React已自动处理XSS，无需额外转义
  }
});

// 提供资源合并函数，支持使用者将库的翻译合并到自身i18n实例
export const mergeLibTranslations = (appI18n) => {
  ['en', 'zh'].forEach(lng => {
    appI18n.addResourceBundle(lng, 'translation', lng === 'en' ? enLocale : zhLocale, true, true);
  });
};

export default libI18n;

2. 使用者的集成方式 #

使用者只需在应用根层级引入库的i18n实例（或合并到自身实例后），用I18NextProvider包裹整个应用即可，所有库组件会自动共享翻译上下文：

场景1：使用者未使用i18next

// 使用者应用的入口文件
import React from 'react';
import ReactDOM from 'react-dom/client';
import { I18NextProvider } from 'react-i18next';
import libI18n from '@your-monorepo/your-lib/i18n';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <I18NextProvider i18n={libI18n}>
    <App />
  </I18NextProvider>
);

场景2：使用者已有自己的i18next配置

// 使用者应用的i18n配置
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import { mergeLibTranslations } from '@your-monorepo/your-lib/i18n';
import appEnLocale from './locales/en.json';

const appI18n = i18n.createInstance();
appI18n.use(initReactI18next).init({
  resources: {
    en: { translation: appEnLocale }
  },
  lng: 'en'
});

// 合并组件库的翻译资源
mergeLibTranslations(appI18n);

// 入口文件中使用合并后的实例
import { I18NextProvider } from 'react-i18next';
import App from './App';

root.render(
  <I18NextProvider i18n={appI18n}>
    <App />
  </I18NextProvider>
);

额外建议 #

• 在组件库的文档中明确标注集成步骤，包括两种场景的使用方式
• 如果需要支持使用者自定义翻译，可以在i18n初始化时预留配置覆盖入口，比如允许使用者传入自定义的翻译资源
• 组件内部直接使用useTranslation钩子即可，无需额外处理，因为上下文已经由根层级的Provider提供

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