使用Intlayer在Create React App中实现国际化(i18n)

2025-06-12 21:17:05作者：贡沫苏Truman

什么是Intlayer？

Intlayer是一个创新的国际化(i18n)解决方案，专为React应用设计，它提供了一种简单而强大的方式来实现多语言支持。与传统的i18n库不同，Intlayer采用了组件级别的翻译管理方式，让开发者能够更直观地组织和维护多语言内容。

Intlayer的核心优势包括：

声明式字典管理：在组件级别定义翻译内容，保持代码组织清晰
类型安全：自动生成TypeScript类型，提供更好的开发体验
动态元数据本地化：支持路由、页面标题等内容的动态翻译
智能语言检测：自动识别用户偏好语言并提供切换功能

在Create React App中集成Intlayer

1. 安装依赖

首先，我们需要安装Intlayer的核心包和React适配器：

npm install intlayer react-intlayer react-scripts-intlayer

这三个包分别提供：

intlayer：核心功能，包括配置管理、翻译引擎等
react-intlayer：React专用钩子和上下文提供者
react-scripts-intlayer：专为Create React App定制的构建脚本

2. 配置项目

创建intlayer.config.ts文件来配置应用支持的语言：

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

这个配置文件还支持更多高级选项，如：

自定义内容目录路径
控制台日志级别
中间件行为配置
本地化URL策略

3. 更新项目脚本

修改package.json中的脚本，使用Intlayer提供的构建工具：

{
  "scripts": {
    "start": "react-scripts-intlayer start",
    "build": "react-scripts-intlayer build",
    "transpile": "intlayer build"
  }
}

4. 创建内容字典

Intlayer采用声明式的内容管理方式。创建一个内容文件，例如app.content.tsx：

import { t, type Dictionary } from "intlayer";
import React from "react";

const appContent = {
  key: "app",
  content: {
    getStarted: t<React.ReactNode>({
      en: <>Edit <code>src/App.tsx</code> and save to reload</>,
      fr: <>Éditez <code>src/App.tsx</code> et enregistrez pour recharger</>,
      es: <>Edita <code>src/App.tsx</code> y guarda para recargar</>,
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
} satisfies Dictionary;

export default appContent;

内容字典的特点：

支持嵌套结构
可以直接嵌入JSX
类型安全，编译时检查
自动生成翻译键

5. 在组件中使用翻译

在React组件中，我们可以通过useIntlayer钩子访问翻译内容：

import { IntlayerProvider, useIntlayer } from "react-intlayer";

function AppContent() {
  const content = useIntlayer("app");

  return (
    <div className="App">
      {content.getStarted}
      <a href={content.reactLink.href.value}>
        {content.reactLink.content}
      </a>
    </div>
  );
}

function App() {
  return (
    <IntlayerProvider>
      <AppContent />
    </IntlayerProvider>
  );
}

6. 实现语言切换（可选）

添加语言切换功能可以让用户自由选择界面语言：

import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

function LocaleSwitcher() {
  const { setLocale } = useLocale();

  return (
    <div>
      <button onClick={() => setLocale(Locales.ENGLISH)}>English</button>
      <button onClick={() => setLocale(Locales.FRENCH)}>Français</button>
      <button onClick={() => setLocale(Locales.SPANISH)}>Español</button>
    </div>
  );
}

7. 实现本地化路由（可选）

对于SEO友好的多语言网站，我们可以实现基于URL的语言前缀：

import { BrowserRouter, Routes, Route } from "react-router-dom";
import { Locales } from "intlayer";
import { IntlayerProvider } from "react-intlayer";

function LocaleRouter({ children }) {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/en/*" element={
          <IntlayerProvider locale={Locales.ENGLISH}>
            {children}
          </IntlayerProvider>
        }/>
        <Route path="/fr/*" element={
          <IntlayerProvider locale={Locales.FRENCH}>
            {children}
          </IntlayerProvider>
        }/>
        <Route path="/*" element={
          <IntlayerProvider locale={Locales.ENGLISH}>
            {children}
          </IntlayerProvider>
        }/>
      </Routes>
    </BrowserRouter>
  );
}