使用Intlayer与Create React App实现国际化(i18n)开发指南

2025-06-12 12:05:55作者：农烁颖Land

什么是Intlayer？

Intlayer是一个专为现代Web应用设计的国际化(i18n)解决方案库，它通过组件化的方式简化多语言管理流程。相比传统国际化方案，Intlayer具有以下显著优势：

声明式字典管理：在组件级别直接定义多语言内容
动态本地化：支持元数据、路由和内容的实时语言切换
完整的TypeScript支持：自动生成类型定义，提供代码提示和错误检查
智能语言检测：自动识别用户偏好语言并动态切换

环境准备与项目初始化

系统要求

确保开发环境满足：

Node.js 16或更高版本
npm/yarn/pnpm包管理器
Create React App创建的项目基础结构

安装核心依赖

根据项目使用的包管理器选择对应命令：

# npm用户
npm install intlayer react-intlayer react-scripts-intlayer

# yarn用户
yarn add intlayer react-intlayer react-scripts-intlayer

# pnpm用户
pnpm add intlayer react-intlayer react-scripts-intlayer

各包功能说明：

intlayer：核心国际化功能包，提供配置管理、内容编译等基础能力
react-intlayer：React集成包，包含上下文提供者和常用hooks
react-scripts-intlayer：Create React App适配层，扩展构建配置

项目配置详解

基础配置

在项目根目录创建intlayer.config.ts配置文件：

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  content: {
    contentDir: "./src/locales", // 自定义内容文件目录
    extensions: [".content.ts", ".content.json"] // 支持的文件扩展
  }
};

export default config;

关键配置项说明：

locales：项目支持的语言列表
defaultLocale：默认回退语言
contentDir：多语言内容文件存放目录
extensions：识别的内容文件扩展名

构建脚本调整

修改package.json中的scripts部分：

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

多语言内容管理实践

内容文件结构

推荐按功能模块组织内容文件，例如：

src/
  locales/
    common/
      header.content.ts
      footer.content.ts
    pages/
      home.content.ts
      about.content.ts

内容文件示例

以React组件形式定义多语言内容：

import { t } from "intlayer";
import React from "react";

export const homeContent = {
  key: "home",
  content: {
    title: t({
      en: "Welcome to our website",
      zh: "欢迎访问我们的网站",
      ja: "当サイトへようこそ"
    }),
    description: t<React.ReactNode>({
      en: <p>Discover our amazing products</p>,
      zh: <p>探索我们的优质产品</p>,
      ja: <p>素晴らしい商品をご覧ください</p>
    }),
    ctaButton: {
      text: t({
        en: "Get Started",
        zh: "立即开始",
        ja: "始めましょう"
      }),
      link: "/start"
    }
  }
};

内容定义特点：

支持纯文本和JSX内容
结构化组织相关内容
类型安全的属性访问

在组件中使用国际化内容

基础用法

通过useIntlayer hook获取内容：

import { useIntlayer } from "react-intlayer";

function HomePage() {
  const { title, description, ctaButton } = useIntlayer("home");
  
  return (
    <div>
      <h1>{title}</h1>
      {description}
      <a href={ctaButton.link}>{ctaButton.text}</a>
    </div>
  );
}

语言切换实现

添加语言切换组件：

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

function LanguageSwitcher() {
  const { locale, setLocale } = useLocale();
  
  return (
    <div>
      <button 
        disabled={locale === Locales.ENGLISH}
        onClick={() => setLocale(Locales.ENGLISH)}
      >
        English
      </button>
      <button 
        disabled={locale === Locales.CHINESE}
        onClick={() => setLocale(Locales.CHINESE)}
      >
        中文
      </button>
    </div>
  );
}

高级路由国际化方案

基于React Router的实现

创建支持多语言前缀的路由系统：

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

function LocaleRouter() {
  const { locale } = useLocale();
  
  return (
    <BrowserRouter>
      <IntlayerProvider locale={locale}>
        <Routes>
          <Route path="/:lang/" element={<Layout />}>
            <Route path="home" element={<Home />} />
            <Route path="about" element={<About />} />
          </Route>
          <Route path="*" element={<RedirectToLocalized />} />
        </Routes>
      </IntlayerProvider>
    </BrowserRouter>
  );
}

function RedirectToLocalized() {
  const { defaultLocale } = useLocale();
  // 实际项目中应从浏览器或用户设置获取首选语言
  return <Navigate to={`/${defaultLocale}/home`} replace />;
}