用途:在 React / React Native 应用中实现国际化(i18n)。i18next 是核心翻译引擎,负责配置、复数、插值与格式化;react-i18next 是 React 绑定层,通过 hooks、HOC、render props 和 Trans 组件把 i18next 接入组件。
安装:npm install react-i18next i18next --save;常用配套包 npm install i18next-http-backend i18next-browser-languagedetector --save。
配置:在入口旁创建 i18n.js,作为唯一配置来源。最小配置使用内联 resources,设置 lng、fallbackLng 与 interpolation.escapeValue: false。生产配置可加 Backend(从 /public/locales/{lng}/{ns}.json 加载)和 LanguageDetector,并在入口先 import './i18n'。
主要 API:useTranslation hook(函数组件首选,支持命名空间、keyPrefix、固定 lng、useSuspense: false);withTranslation HOC(类组件);Translation render prop;Trans 组件(翻译含内嵌 HTML 或组件的 JSX,支持命名组件与基础 HTML 标签)。
常见模式:语言切换用 i18n.changeLanguage;组件外可用导入的 i18n 实例调用 i18n.t;多实例或 SSR 用 I18nextProvider;命名空间可拆分文件并懒加载;支持插值、复数(_one/_other)、上下文(_male/_female)与嵌套 $t()。
TypeScript 需 react-i18next >= 13.0.0 与 i18next >= 23.0.1,按官方指南做类型增强。SSR 场景:Next.js App Router 直接用 i18next,Pages Router 用 next-i18next,Remix 用 remix-i18next,Gatsby 用 gatsby-plugin-react-i18next,自定义 SSR 用 useSSR 或 withSSR。测试可用 Jest mock、导出裸组件传 t,或完整 i18next 配置。
限制:默认 useTranslation 会触发 Suspense,需包裹 Suspense fallback;关闭后需自行处理 ready 状态。Trans 仅用于需嵌入 React 元素的场景,纯文本应使用 t()。具体版本要求与选项默认值以资料为准,未提供的收费、平台等信息暂未提供。