Zemynzh
返回博客

Intlayer 国际化框架完整指南

深入了解 Intlayer 国际化框架，学习组件级内容管理、AI 驱动翻译和可视化编辑等核心特性

Zemynzh
发布于: 2025/8/18
15 分钟阅读
intlayerinternationalizationi18nreactnextjsvue

Intlayer 国际化框架完整指南

概述

Intlayer 是一个现代化的国际化框架，采用组件级内容管理理念，支持 React、Next.js、Vue.js 等多个前端框架。它彻底改变了传统国际化方案，让多语言开发变得更加简单和高效。

核心特性

  • 🏗️ 组件级内容管理 - 内容文件与组件同目录，便于维护
  • 🤖 AI 驱动翻译 - 支持多种 AI 提供商自动翻译
  • 🎨 可视化编辑器 - 实时编辑内容，无需修改代码
  • 📦 多框架支持 - React、Next.js、Vue.js、Nuxt 等
  • 🔧 TypeScript 支持 - 完整的类型安全
  • 🌐 CMS 集成 - 远程内容管理

快速开始

安装

npm install intlayer next-intlayer

基础配置

// intlayer.config.ts
import { Locales, type IntlayerConfig } from "intlayer";

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

export default config;

核心架构

工作原理

Intlayer 采用三步架构：

  1. 构建步骤 - 扫描内容声明文件生成字典
  2. 解释步骤 - 运行时通过 useIntlayer 获取内容
  3. 响应性 - useIntlayer 返回 Proxy 对象，setLocale() 自动触发重渲染

目录结构

src/
├── components/
│   └── MyComponent/
│       ├── index.tsx
│       └── index.content.ts  # 内容声明文件
└── intlayer.config.ts

内容声明

基础翻译

// component.content.ts
import { t, type Dictionary } from "intlayer";

export default {
  key: "my-component",
  content: {
    title: t({
      zh: "标题",
      en: "Title",
    }),
  },
} satisfies Dictionary;

九种内容类型

Intlayer 提供了丰富的内容类型支持：

  1. 翻译 (t) - 基础多语言文本
  2. 条件 (cond) - 基于条件显示内容
  3. 枚举 (enu) - 基于数量的复数形式
  4. 性别 (gender) - 基于性别的内容
  5. 插入 (insert) - 模板字符串 {{name}}
  6. 文件 (file) - 外部文件嵌入
  7. Markdown (md) - 富文本内容
  8. 嵌套 (nest) - 引用其他字典
  9. 函数 - 动态获取内容

Next.js 集成

1. 安装和配置

npm install intlayer next-intlayer

// next.config.mjs
import { withIntlayer } from "next-intlayer/server";

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withIntlayer(nextConfig);

2. 中间件设置

// src/middleware.ts
export { intlayerMiddleware as default } from "next-intlayer/middleware";

export const config = {
  matcher: "/((?!api|static|.*\\..*|_next).*)",
};

3. 布局配置

// src/app/layout.tsx
import { NextLayoutIntlayer } from "next-intlayer";
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

const RootLayout: NextLayoutIntlayer = ({ children, params: { locale } }) => (
  <html lang={locale}>
    <body className={inter.className}>
      <IntlayerClientProvider locale={locale}>
        {children}
      </IntlayerClientProvider>
    </body>
  </html>
);

export { generateStaticParams } from "next-intlayer";
export default RootLayout;

4. 页面使用

// src/app/[locale]/page.tsx
import { useIntlayer } from "next-intlayer";

const HomePage = () => {
  const { title, description } = useIntlayer("home-page");
  
  return (
    <div>
      <h1>{title}</h1>
      <p>{description}</p>
    </div>
  );
};

export default HomePage;

CLI 工具

核心命令

# 构建字典
npx intlayer build [--watch]

# AI 自动翻译
npx intlayer fill

# 远程同步
npx intlayer push  # 推送到 CMS
npx intlayer pull  # 从 CMS 拉取

# 配置管理
npx intlayer config get
npx intlayer config push

# 文档翻译
npx intlayer doc translate
npx intlayer doc review

高级功能

自动填充翻译

// 主文件
export default {
  key: "example",
  autoFill: "./example.content.json", // 自动生成其他语言
  content: {
    title: "Hello World"
  }
};

条件内容

import { cond } from "intlayer";

export default {
  key: "conditional",
  content: {
    message: cond({
      true: "已登录",
      false: "未登录",
      fallback: "状态未知"
    })
  }
};

// 使用
const { message } = useIntlayer("conditional");
return <div>{message(isLoggedIn)}</div>;

插值内容

import { insert } from "intlayer";

export default {
  key: "greeting",
  content: {
    welcome: insert("欢迎 {{name}}，今天是 {{date}}")
  }
};

// 使用
const { welcome } = useIntlayer("greeting");
return <div>{welcome({ name: "张三", date: "2024年" })}</div>;

最佳实践

1. 响应性使用

// ✅ 正确 - 保持响应性
const content = useIntlayer("myContent");
return <div>{content.title}</div>;

// ✅ 正确 - 解构使用
const { title } = useIntlayer("myContent");
return <div>{title}</div>;

// ❌ 错误 - 破坏响应性
const content = useIntlayer("myContent");
const title = content.title; // 静态值

2. 语言切换

const { locale, setLocale } = useLocale();

// 切换语言会自动触发重渲染
setLocale("en");

3. 内容组织

src/
├── components/
│   └── Header/
│       ├── index.tsx
│       └── index.content.ts  # 组件级内容
├── pages/
│   └── home/
│       ├── index.tsx
│       └── index.content.ts  # 页面级内容
└── shared/
    └── common.content.ts     # 共享内容

配置系统

完整配置选项

// intlayer.config.ts
import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // 国际化配置
  internationalization: {
    locales: [Locales.CHINESE, Locales.ENGLISH],
    defaultLocale: Locales.CHINESE,
    strictMode: "strict", // "strict" | "inclusive" | "loose"
  },
  
  // 内容配置
  content: {
    fileExtensions: [".content.ts", ".content.js", ".content.json"],
    contentDir: ["src"],
    dictionariesDir: ".intlayer/dictionaries",
  },
  
  // 中间件配置
  middleware: {
    headerName: "x-intlayer-locale",
    cookieName: "intlayer-locale",
    prefixDefault: false,
    basePath: "",
    noPrefix: false,
  },
  
  // 编辑器配置
  editor: {
    applicationURL: "http://localhost:3000",
    port: 8000,
    enabled: true,
  },
  
  // AI 配置
  ai: {
    provider: "openai", // "openai" | "anthropic" | "mistral" | "deepseek" | "gemini"
    apiKey: process.env.OPENAI_API_KEY,
    model: "gpt-4",
    temperature: 0.1,
  },
  
  // 构建优化
  build: {
    optimize: true,
    importMode: "static", // "static" | "dynamic" | "async"
  },
};

export default config;

总结

Intlayer 提供了完整的国际化解决方案，具有以下优势：

  • 🏗️ 组件级管理 - 内容与组件同目录，便于维护
  • 🤖 AI 驱动 - 自动翻译和内容生成，提高效率
  • 🎨 可视化编辑 - 实时内容编辑，降低技术门槛
  • 📦 多框架支持 - 一套方案，多框架适用
  • 🔧 类型安全 - 完整 TypeScript 支持，开发体验佳
  • 🌐 CMS 集成 - 远程内容管理，支持团队协作

通过 Intlayer，开发者可以轻松构建多语言应用，同时保持代码的可维护性和扩展性。无论是个人项目还是企业级应用，Intlayer 都能提供强大的国际化支持。