如何在 React 项目中使用 react-i18next？

react-i18next 简介

react-i18next 是 i18next 的 React 专用绑定库，提供了 React Hooks 和组件，使国际化在 React 应用中更加便捷。

安装

bash
npm install react-i18next i18next
# 或
yarn add react-i18next i18next

基本配置

初始化

javascript
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(Backend) // 加载翻译资源
  .use(LanguageDetector) // 检测用户语言
  .use(initReactI18next) // 绑定 react-i18next
  .init({
    fallbackLng: 'en',
    debug: true,
    interpolation: {
      escapeValue: false // React 已经处理了 XSS
    }
  });

export default i18n;

在应用入口引入

javascript
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import './i18n'; // 引入 i18n 配置

ReactDOM.render(<App />, document.getElementById('root'));

使用 useTranslation Hook

基本用法

javascript
import React from 'react';
import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  
  return <h1>{t('welcome')}</h1>;
}

指定命名空间

javascript
function MyComponent() {
  const { t } = useTranslation('common');
  
  return <button>{t('save')}</button>;
}

多个命名空间

javascript
function MyComponent() {
  const { t } = useTranslation(['common', 'errors']);
  
  return (
    <div>
      <button>{t('common:save')}</button>
      <p>{t('errors:notFound')}</p>
    </div>
  );
}

使用 Trans 组件

基本用法

javascript
import { Trans } from 'react-i18next';

function MyComponent() {
  return (
    <Trans i18nKey="user.profile">
      Welcome <strong>{{name}}</strong> to your profile
    </Trans>
  );
}

// 翻译资源
// "user.profile": "Welcome <1>{{name}}</1> to your profile"

嵌套组件

javascript
<Trans i18nKey="description">
  Click <Link to="/about">here</Link> to learn more
</Trans>

使用 withTranslation HOC

javascript
import { withTranslation } from 'react-i18next';

class MyComponent extends React.Component {
  render() {
    const { t } = this.props;
    return <h1>{t('title')}</h1>;
  }
}

export default withTranslation()(MyComponent);

使用 I18nextProvider

javascript
import { I18nextProvider } from 'react-i18next';
import i18n from './i18n';

function App() {
  return (
    <I18nextProvider i18n={i18n}>
      <MyComponent />
    </I18nextProvider>
  );
}

语言切换

创建语言切换器

javascript
import { useTranslation } from 'react-i18next';

function LanguageSwitcher() {
  const { i18n } = useTranslation();
  
  const changeLanguage = (lng) => {
    i18n.changeLanguage(lng);
  };
  
  return (
    <div>
      <button onClick={() => changeLanguage('en')}>English</button>
      <button onClick={() => changeLanguage('zh')}>中文</button>
    </div>
  );
}

监听语言变化

javascript
function MyComponent() {
  const { t, i18n } = useTranslation();
  const [currentLanguage, setCurrentLanguage] = useState(i18n.language);
  
  useEffect(() => {
    const handleLanguageChange = (lng) => {
      setCurrentLanguage(lng);
    };
    
    i18n.on('languageChanged', handleLanguageChange);
    
    return () => {
      i18n.off('languageChanged', handleLanguageChange);
    };
  }, [i18n]);
  
  return <p>Current language: {currentLanguage}</p>;
}

延迟加载命名空间

javascript
function LazyComponent() {
  const { t, ready } = useTranslation('lazyNamespace', { useSuspense: false });
  
  if (!ready) {
    return <div>Loading...</div>;
  }
  
  return <p>{t('content')}</p>;
}

最佳实践

1. 按需加载: 使用命名空间和延迟加载优化性能
2. 类型安全: TypeScript 项目使用类型定义
3. 错误处理: 处理缺失的翻译
4. 测试: 编写国际化相关的单元测试
5. 代码分割: 将翻译资源与应用代码分离