第三章、React项目国际化介绍（`react-i18next`）

React项目国际化介绍（react-i18next）

在 React + TypeScript 项目中配置 国际化 (i18n) ，推荐使用主流方案：react-i18next （即 i18next 的 React 适配库）。

一、安装依赖

在项目根目录执行：

npm install i18next react-i18next i18next-browser-languagedetector

二、目录结构推荐

src/
├── i18n/
│   ├── index.ts                # i18n 初始化配置
│   ├── locales/
│   │   ├── en/
│   │   │   └── translation.json
│   │   └── zh/
│   │       └── translation.json
├── components/
│   └── LanguageSwitcher.tsx    # 语言切换组件
├── App.tsx
└── index.tsx

三、i18n 初始化配置

src/i18n/index.ts

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

// 导入语言包
import en from "./locales/en/translation.json";
import zh from "./locales/zh/translation.json";

i18n
  .use(LanguageDetector) // 自动检测用户语言（浏览器设置、localStorage等）
  .use(initReactI18next) // React 绑定
  .init({
    fallbackLng: "en", // 默认语言
    debug: false,       // 开发时可设为 true 查看加载日志
    interpolation: {
      escapeValue: false, // React 已经自动防止 XSS
    },
    resources: {
      en: { translation: en },
      zh: { translation: zh },
    },
    detection: {
      // 可选：指定检测顺序和缓存方式
      order: ["localStorage", "navigator"],
      caches: ["localStorage"],
    },
  });

export default i18n;

四、语言文件

src/i18n/locales/en/translation.json

{
  "welcome": "Welcome to our site!",
  "language": "Language",
  "change_language": "Change Language"
}

src/i18n/locales/zh/translation.json

{
  "welcome": "欢迎来到我们的网站！",
  "language": "语言",
  "change_language": "切换语言"
}

五、在入口文件中加载 i18n

src/index.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./i18n"; 

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

六、在组件中使用国际化

src/App.tsx

import React from "react";
import { useTranslation } from "react-i18next";
import LanguageSwitcher from "./components/LanguageSwitcher";

const App: React.FC = () => {
  const { t } = useTranslation();

  return (
    <div className="p-8">
      <h1>{t("welcome")}</h1>
      <p>{t("language")}: {t("change_language")}</p>
      <LanguageSwitcher />
    </div>
  );
};

export default App;

七、语言切换组件

src/components/LanguageSwitcher.tsx

import React from "react";
import { useTranslation } from "react-i18next";

const LanguageSwitcher: React.FC = () => {
  const { i18n } = useTranslation();

  const changeLanguage = (lng: string) => {
    i18n.changeLanguage(lng);
  };

  return (
    <div>
      <button onClick={() => changeLanguage("zh")} className="mr-2">
        中文
      </button>
      <button onClick={() => changeLanguage("en")}>
        English
      </button>
    </div>
  );
};

export default LanguageSwitcher;