@intlayer/docs 5.8.0-canary.0 → 5.8.1-canary.0

package/blog/zh/next-i18next_vs_next-intl_vs_intlayer.md

@@ -1,14 +1,14 @@
 ---
-createdAt: 2024-08-11
-updatedAt: 2025-06-29
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
 title: next-i18next vs next-intl vs Intlayer
-description: 比较Next.js应用程序的next-i18next与next-intl与Intlayer
+description: 比较 next-i18next、next-intl 和 Intlayer 在 Next.js 应用国际化（i18n）中的表现
 keywords:
   - next-intl
   - next-i18next
   - Intlayer
   - 国际化
-  - 文档
+  - 博客
   - Next.js
   - JavaScript
   - React
@@ -17,269 +17,146 @@ slugs:
   - next-i18next-vs-next-intl-vs-intlayer
 ---
 
-# next-i18next VS next-intl VS Intlayer | Next.js 国际化 (i18n)
+# next-i18next VS next-intl VS intlayer | Next.js 国际化（i18n）
 
-下面是 **三个流行库** 进行 Next.js 应用国际化 (i18n) 的简要比较：**next-intl**、**next-i18next** 和 **Intlayer**。
+本指南比较了三种广泛使用的 **Next.js** 国际化方案：**next-intl**、**next-i18next** 和 **Intlayer**。
+我们重点关注 **Next.js 13+ App Router**（配合 **React 服务器组件**），并评估：
 
-本文档强调关键标准：
+1. **架构与内容组织**
+2. **TypeScript 与安全性**
+3. **缺失翻译处理**
+4. **路由与中间件**
+5. **性能与加载行为**
+6. **开发者体验（DX）、工具链与维护**
+7. **SEO 与大规模项目的可扩展性**
 
-1. **架构**（将翻译与其组件保持紧密）
-2. **TypeScript 支持**
-3. **缺失翻译的管理**
-4. **服务器组件支持**
-5. **增强的路由和中间件** 适用于 Next.js
-6. **设置的简单性**
-
-该指南还提供了对 **Intlayer** 的 **深入了解**，展示了它为什么可以成为一个强大的选择, , 特别是对于 Next.js 13+，包括 **App Router** 和 **服务器组件**。
+> **简而言之**：这三者都能实现 Next.js 应用的本地化。如果你需要**组件范围的内容管理**、**严格的 TypeScript 类型**、**构建时缺失键检查**、**支持 Tree-shaking 的词典**，以及**一流的 App Router 和 SEO 辅助工具**，那么 **Intlayer** 是最完整、最现代的选择。
 
 ---
 
-## 各库概述
-
-### 1. next-intl
+## 高层定位
 
-**主要焦点**：快速简便的设置，采用轻量级的本地化方式。
+- **next-intl** - 轻量且直观的消息格式化，具备扎实的 Next.js 支持。通常采用集中式目录；开发体验简单，但安全性和大规模维护主要依赖于你自己。
+- **next-i18next** - 以 Next.js 形式呈现的 i18next。生态系统成熟，通过插件（例如 ICU）提供丰富功能，但配置可能冗长，且随着项目增长，目录往往趋于集中化。
+- **Intlayer** - 面向组件的 Next.js 内容模型，**严格的 TypeScript 类型**，**构建时检查**，**摇树优化**，**内置中间件和 SEO 辅助工具**，可选的 **可视化编辑器/CMS**，以及 **AI 辅助翻译**。
 
-- **架构**：鼓励将翻译放在单一文件夹中（例如，`locales/`），但也允许多种策略。不严格执行“每个组件一个翻译”的架构。
-- **TypeScript 支持**：基础的 TypeScript 集成。存在一些类型定义，但并不以从翻译文件自动生成 TypeScript 定义为主要方向。
-- **缺失翻译**：基本的回退机制。默认情况下，回退到一个键或默认语言字符串。没有强大的开箱即用的工具来进行高级缺失翻译检查。
-- **服务器组件支持**：通常与 Next.js 13+ 一起工作，但对于深层服务器端使用（例如，复杂动态路由的服务器组件），模式不够专用。
-- **路由和中间件**：中间件支持是可能的，但有限。通常依赖于 Next.js 的 `Middleware` 进行语言检测，或手动配置以重写语言路径。
-- **设置简单性**：非常简单。需要最少的样板代码。
+---
 
-**使用时机**：当你想要一种更简单的方法或熟悉以更传统的方式管理你的翻译（如一个包含语言 JSON 文件的文件夹）时。
+## 并列功能对比（聚焦 Next.js）
+
+| 功能                                   | `next-intlayer`（Intlayer）                                                            | `next-intl`                                                | `next-i18next`                                             |
+| -------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
+| **组件附近的翻译**                     | ✅ 是，内容与每个组件共置                                                              | ❌ 否                                                      | ❌ 否                                                      |
+| **TypeScript 集成**                    | ✅ 高级，自动生成严格类型                                                              | ✅ 良好                                                    | ⚠️ 基础                                                    |
+| **缺失翻译检测**                       | ✅ TypeScript 错误高亮和构建时错误/警告                                                | ⚠️ 运行时回退                                              | ⚠️ 运行时回退                                              |
+| **丰富内容（JSX/Markdown/组件）**      | ✅ 直接支持                                                                            | ❌ 不支持丰富节点                                          | ⚠️ 有限支持                                                |
+| **AI 驱动的翻译**                      | ✅ 是，支持多个 AI 提供商。可使用您自己的 API 密钥。考虑您的应用程序和内容范围的上下文 | ❌ 否                                                      | ❌ 否                                                      |
+| **可视化编辑器**                       | ✅ 是，本地可视化编辑器 + 可选 CMS；可外部化代码库内容；可嵌入                         | ❌ 否 / 可通过外部本地化平台获得                           | ❌ 否 / 可通过外部本地化平台获得                           |
+| **本地化路由**                         | ✅ 是，开箱即用支持本地化路径（兼容 Next.js 和 Vite）                                  | ✅ 内置，App Router 支持 `[locale]` 路由段                 | ✅ 内置                                                    |
+| **动态路由生成**                       | ✅ 是                                                                                  | ✅ 是                                                      | ✅ 是                                                      |
+| **复数形式**                           | ✅ 基于枚举的模式                                                                      | ✅ 良好                                                    | ✅ 良好                                                    |
+| **格式化（日期、数字、货币）**         | ✅ 优化的格式化器（底层使用 Intl）                                                     | ✅ 良好（Intl 辅助工具）                                   | ✅ 良好（Intl 辅助工具）                                   |
+| **内容格式**                           | ✅ .tsx, .ts, .js, .json, .md, .txt, (.yaml 进行中)                                    | ✅ .json, .js, .ts                                         | ⚠️ .json                                                   |
+| **ICU 支持**                           | ⚠️ 进行中                                                                              | ✅ 是                                                      | ⚠️ 通过插件（`i18next-icu`）                               |
+| **SEO 辅助工具（hreflang，网站地图）** | ✅ 内置工具：网站地图、robots.txt、元数据辅助工具                                      | ✅ 良好                                                    | ✅ 良好                                                    |
+| **生态系统 / 社区**                    | ⚠️ 规模较小但增长迅速且活跃                                                            | ✅ 中等规模，专注于 Next.js                                | ✅ 中等规模，专注于 Next.js                                |
+| **服务器端渲染与服务器组件**           | ✅ 是，针对 SSR / React 服务器组件进行了优化                                           | ⚠️ 支持页面级别，但需要在组件树上传递 t 函数给子服务器组件 | ⚠️ 支持页面级别，但需要在组件树上传递 t 函数给子服务器组件 |
+| **Tree-shaking（仅加载使用的内容）**   | ✅ 是，通过 Babel/SWC 插件在构建时按组件进行                                           | ⚠️ 部分支持                                                | ⚠️ 部分支持                                                |
+| **懒加载**                             | ✅ 是，按语言环境 / 按字典                                                             | ✅ 是（按路由/按语言环境），需要命名空间管理               | ✅ 是（按路由/按语言环境），需要命名空间管理               |
+| **清除未使用内容**                     | ✅ 是，按字典在构建时                                                                  | ❌ 否，可以通过命名空间管理手动处理                        | ❌ 否，可以通过命名空间管理手动处理                        |
+| **大型项目管理**                       | ✅ 鼓励模块化，适合设计系统                                                            | ✅ 通过设置实现模块化                                      | ✅ 通过设置实现模块化                                      |
 
 ---
 
-### 2. next-i18next
+## 深度比较
 
-**主要焦点**：使用 `i18next` 背后的成熟解决方案，广泛应用于 Next.js 项目。
+### 1) 架构与可扩展性
 
-- **架构**：通常将翻译组织在 `public/locales` 文件夹中。并不是专门设计为将翻译“靠近”每个组件，尽管你可以手动采用不同的结构。
-- **TypeScript 支持**：合理的 TypeScript 覆盖，但需要自定义配置以进行类型化翻译和类型化钩子。
-- **缺失翻译**：i18next 提供插值/回退机制。然而，缺失翻译检测通常需要额外设置或第三方插件。
-- **服务器组件支持**：已记录基本用法与 Next.js 13 兼容，但高级用法（例如，深度集成服务器组件、动态路由生成）可能比较麻烦。
-- **路由和中间件**：在语言子路径的重写中严重依赖于 Next.js 的 `Middleware`。对于更复杂的设置，你可能需要深入了解高级 i18next 配置。
-- **设置简单性**：对于习惯 i18next 的人来说是熟悉的方式。然而，在需要高级 i18n 特性时（命名空间、多种回退语言等）可能会增加更多样板代码。
+- **next-intl / next-i18next**：默认每个语言环境使用**集中式目录**（i18next 中还有**命名空间**）。初期运行良好，但随着耦合增加和键值频繁变动，往往会成为一个庞大的共享区域。
+- **Intlayer**：鼓励将**每个组件**（或每个功能）的字典与其对应的代码**共置**。这降低了认知负担，简化了 UI 组件的复制/迁移，并减少了跨团队的冲突。未使用的内容也更容易被发现和清理。
 
-**使用时机**：当你已经致力于 `i18next` 生态系统或有现有 i18next 基础的翻译时。
+**重要原因：** 在大型代码库或设计系统设置中，**模块化内容**比单一目录更具扩展性。
 
 ---
 
-### 3. Intlayer
-
-**主要焦点**：一个现代的开源 i18n 库，专门为 Next.js **App Router**（12, 13, 14 和 15）量身定制，内置支持 **服务器组件** 和 **Turbopack**。
+### 2) TypeScript 与安全性
 
-#### 主要优点
+- **next-intl**：提供了扎实的 TypeScript 支持，但**默认情况下键并非严格类型化**；你需要手动维护安全模式。
+- **next-i18next**：为钩子提供基础类型定义；**严格的键类型化需要额外的工具/配置**。
+- **Intlayer**：**从您的内容生成严格类型**。**IDE 自动补全**和**编译时错误**可以在部署前捕获拼写错误和缺失的键。
 
-1. **架构**
+**重要原因：** 强类型将失败提前到**左侧**（CI/构建阶段），而不是在**右侧**（运行时）出现。
 
-   - 鼓励将 **翻译紧密放置于组件旁边**。每个页面或组件可以拥有自己的 `.content.ts`（或 JSON）文件, , 无须在巨大的翻译文件夹中翻找。
-   - 这使得你的代码更加 **模块化和可维护**，特别是在大型代码库中。
-
-2. **TypeScript 支持**
-
-   - **自动生成的类型定义**：一旦你定义了内容，Intlayer 将生成可以支持自动完成并捕捉翻译错误的类型。
-   - 最小化运行时错误，比如缺失键，并直接在你的 IDE 中提供高级 **自动完成**。
-
-3. **缺失翻译的管理**
+---
 
-   - 在构建期间，Intlayer 可以 **检测缺失的翻译键** 并抛出警告或错误。
-   - 这确保你永远不会在多语言之间意外发布缺失文本。
+### 3）缺失翻译处理
 
-4. **针对服务器组件的优化**
+- **next-intl / next-i18next**：依赖**运行时回退**（例如，显示键名或默认语言）。构建不会失败。
+- **Intlayer**：通过**构建时检测**，对缺失的语言或键发出**警告/错误**。
 
-   - 完全支持 Next.js 的 **App Router** 和新的 **服务器组件** 范式。
-   - 提供专门的提供者（`IntlayerServerProvider`、`IntlayerClientProvider`）以 **隔离服务器上下文**（处理 Next.js 13+ 时至关重要）。
+**重要原因：** 在构建时捕获缺口可以防止生产环境出现“神秘字符串”，并符合严格的发布门控。
 
-5. **增强的路由和中间件**
+---
 
-   - 包含一款专用的 [**`intlayerMiddleware`**](#) 用于 **自动语言检测**（通过 cookies 或浏览器头）和高级路由生成。
-   - 动态处理本地化路径（例如，`/en-US/about` 与 `/fr/about`），配置最小化。
-   - 提供助手方法如 `getMultilingualUrls` 用于生成替代语言链接（非常适合 **SEO**）。
+### 4）路由、中间件和 URL 策略
 
-6. **简化的设置**
-   - 一个配置文件（`intlayer.config.ts`）来定义你的语言、默认语言和集成偏好。
-   - 一个包装插件 `withIntlayer(nextConfig)` 可以 **注入** 所有环境变量和内容监视器。
-   - **没有大型回退配置**, , 该系统旨在“正常工作”，减少摩擦。
+- 三者均支持在 App Router 上使用 **Next.js 本地化路由**。
+- **Intlayer** 进一步提供了 **i18n 中间件**（通过请求头/Cookie 进行语言环境检测）和 **辅助工具**，用于生成本地化 URL 以及 `<link rel="alternate" hreflang="…">` 标签。
 
-> **底线**：Intlayer 是一个现代化的解决方案，旨在 **推动最佳实践**：从 **将翻译紧邻** 其每个 React 组件，到提供 **强大的 TS 支持** 和 **简便的服务器端** 使用，同时 **大幅减少样板代码**。
+**重要原因：** 减少自定义粘合层；实现跨语言环境的 **一致用户体验** 和 **干净的 SEO**。
 
 ---
 
-## 并排特性比较
-
-| **特性**                | **next-intl**             | **next-i18next**               | **Intlayer**                    |
-| ----------------------- | ------------------------- | ------------------------------ | ------------------------------- |
-| **将翻译靠近组件**      | 部分 - 通常一个语言文件夹 | 非默认 - 通常 `public/locales` | **是 - 推荐且简单**             |
-| **TypeScript 自动生成** | 基本 TS 定义              | 基本 TS 支持                   | **是 - 高级开箱即用**           |
-| **缺失翻译检测**        | 主要是回退字符串          | 主要是回退字符串               | **是 - 构建时检查**             |
-| **服务器组件支持**      | 有效但不专用              | 支持但可能冗长                 | **完全支持专用提供者**          |
-| **路由和中间件**        | 手动集成与 Next 中间件    | 通过重写配置提供               | **专用 i18n 中间件 + 高级钩子** |
-| **设置复杂性**          | 简单，最小配置            | 传统，对于高级用法可能冗长     | **一个配置文件 & 插件**         |
-
----
+### 5) 服务器组件（RSC）对齐
 
-## 为什么选择 Intlayer？
+- **所有方案**均支持 Next.js 13+。
+- **Intlayer** 通过一致的 API 和专为 RSC 设计的提供者，平滑处理 **服务器/客户端边界**，避免在组件树中传递格式化器或 t 函数。
 
-对于迁移到或建立在 **Next.js App Router**（版本 13、14 或 15）与 **服务器组件** 之上的团队，Intlayer 提供：
+**重要原因：** 更清晰的思维模型，减少混合树中的边缘情况。
 
-1. **精简的架构**
+---
 
-   - 每个路由或组件都持有自己的翻译。这促进了清晰性和可维护性。
+### 6) 性能与加载行为
 
-2. **强大的 TypeScript 集成**
+- **next-intl / next-i18next**：通过**命名空间**和**路由级拆分**实现部分控制；如果管理不严，存在打包未使用字符串的风险。
+- **Intlayer**：在构建时进行**摇树优化**，并按字典/语言环境**懒加载**。未使用的内容不会被打包。
 
-   - 你获得编译器级别的安全性，避免“拼写错误”或缺失的翻译键。
+**重要原因：** 包体积更小，启动更快，尤其适用于多语言站点。
 
-3. **真实的缺失翻译警报**
+---
 
-   - 如果你忘记了某个键或语言翻译，你将在构建时收到警告（而不是发布不完整的 UI）。
+### 7) 开发体验（DX）、工具链与维护
 
-4. **内置高级路由**
+- **next-intl / next-i18next**：通常需要接入外部平台来处理翻译和编辑工作流。
+- **Intlayer**：内置**免费可视化编辑器**和**可选CMS**（支持Git友好或外部化）。此外，还提供**VSCode扩展**用于内容创作，并支持使用您自己的提供商密钥进行**AI辅助翻译**。
 
-   - 自动语言检测、动态路由生成和简单的本地化 URL 管理均包含在内。
-   - 标准的 `intlayerMiddleware` 不需要深入自定义重写。
+**重要原因：** 降低运营成本，缩短开发者与内容作者之间的反馈循环。
 
-5. **一站式设置**
+---
 
-   - 最少的样板代码：只需定义你的 `intlayer.config.ts`，用 `withIntlayer` 包装 `next.config`，并添加官方中间件。
-   - 清晰、直接的用法，适用于 **服务器** 和 **客户端** 组件，通过 `IntlayerServerProvider` 和 `IntlayerClientProvider` 实现。
+## 何时选择哪种方案？
 
-6. **SEO 友好**
-   - 内置的助手（`getMultilingualUrls`、`hrefLang` 属性等）使得生成符合 SEO 的页面和网站地图变得简单。
+- 如果你想要一个**极简**的解决方案，且对集中式目录感到舒适，并且你的应用是**小型到中型**，请选择 **next-intl**。
+- 如果你需要 **i18next 的插件生态系统**（例如，通过插件实现高级 ICU 规则），且你的团队已经熟悉 i18next，愿意接受**更多配置**以获得灵活性，请选择 **next-i18next**。
+- 如果你重视**组件范围的内容管理**、**严格的 TypeScript**、**构建时保证**、**摇树优化**，以及**内置的路由/SEO/编辑工具**，尤其是针对 **Next.js App Router** 和**大型模块化代码库**，请选择 **Intlayer**。
 
 ---
 
-## 示例：Intlayer 的实际应用
-
-以下是一个 _非常_ 简明的代码片段，展示了如何在 Next.js 15 项目中利用 Intlayer。有关详细信息和代码示例，请 [查看完整的 Intlayer 指南](#)。
-
-<details>
-<summary>逐步示例</summary>
-
-1. **安装和配置**
-
-   ```bash
-   npm install intlayer next-intlayer
-   ```
-
-   ```ts
-   // 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;
-   ```
-
-2. **使用插件**
-
-   ```ts
-   // next.config.mjs
-   import { withIntlayer } from "next-intlayer/server";
-
-   /** @type {import('next').NextConfig} */
-   const nextConfig = {};
-
-   export default withIntlayer(nextConfig);
-   ```
-
-3. **添加中间件**
-
-   ```ts
-   // src/middleware.ts
-   export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
-
-   export const config = {
-     matcher:
-       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
-   };
-   ```
-
-4. **创建本地化布局**
-
-   ```tsx
-   // src/app/[locale]/layout.tsx
-   import { getHTMLTextDir } from "intlayer";
-   import { NextLayoutIntlayer } from "next-intlayer";
-
-   const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
-     const { locale } = params;
-     return (
-       <html lang={locale} dir={getHTMLTextDir(locale)}>
-         <body>{children}</body>
-       </html>
-     );
-   };
-
-   export { generateStaticParams } from "next-intlayer";
-   export default LocaleLayout;
-   ```
-
-5. **声明并使用内容**
-
-   ```tsx
-   // src/app/[locale]/page.content.ts
-   import { t } from "intlayer";
-
-   export default {
-     key: "page",
-     content: {
-       getStarted: {
-         main: t({
-           en: "Get started by editing",
-           fr: "Commencez par éditer",
-           es: "Comience por editar",
-         }),
-         pageLink: "src/app/page.tsx",
-       },
-     },
-   };
-   ```
-
-   ```tsx
-   // src/app/[locale]/page.tsx
-   import { IntlayerServerProvider } from "next-intlayer/server";
-   import { IntlayerClientProvider, useIntlayer } from "next-intlayer";
-
-   const PageContent = () => {
-     const { content } = useIntlayer("page");
-     return (
-       <>
-         <p>{content.getStarted.main}</p>
-         <code>{content.getStarted.pageLink}</code>
-       </>
-     );
-   };
-
-   export default function Page({ params }) {
-     return (
-       <IntlayerServerProvider locale={params.locale}>
-         <IntlayerClientProvider locale={params.locale}>
-           <PageContent />
-         </IntlayerClientProvider>
-       </IntlayerServerProvider>
-     );
-   }
-   ```
-
-   </details>
+## 实用迁移注意事项（next-intl / next-i18next → Intlayer）
+
+- **按功能开始**：一次将一个路由或组件迁移到**本地字典**。
+- **并行保留旧目录**：迁移期间搭桥，避免一次性大迁移。
+- **开启严格检查**：让构建时检测及早暴露缺口。
+- **采用中间件和辅助工具**：全站标准化语言检测和SEO标签。
+- **测量包大小**：随着未使用内容被剔除，预期**包体积减少**。
 
 ---
 
 ## 结论
 
-每个解决方案, **next-intl**、**next-i18next** 和 **Intlayer**, 在多语言 Next.js 项目中都证明了其有效性。然而，**Intlayer** 更进一步，通过：
+这三个库都能成功实现核心本地化。区别在于在**现代 Next.js**中，要实现一个健壮、可扩展的方案，你需要付出多少工作量：
 
-- **强烈鼓励组件级翻译架构**
-- 与 **Next.js 13+ 和服务器组件** 无缝集成
-- 提供 **强大的 TypeScript** 自动生成以确保更安全的代码
-- 在构建时处理 **缺失翻译**
-- 提供一个 **简化的单一配置** 方法和增强的路由与中间件
+- 使用 **Intlayer**，**模块化内容**、**严格的 TS**、**构建时安全性**、**摇树优化的包**，以及**一流的 App Router 和 SEO 工具**都是**默认配置**，而非额外负担。
+- 如果您的团队重视多语言、组件驱动应用中的**可维护性和速度**，Intlayer 提供了当今**最完整**的体验。
 
-如果你想要符合 **现代** i18n 特性的解决方案，并且针对 Next.js App Router 寻找 **完全类型化** 的体验，无需手动调整回退逻辑、路由重写或复杂的构建步骤，**Intlayer** 是一个引人注目的选择。它不仅缩短了你的设置时间，还确保了团队对翻译的更可维护、可扩展的方法。
+更多详情请参阅[《为什么选择 Intlayer？》文档](https://intlayer.org/doc/why)。