@intlayer/docs 9.4.4 → 9.5.0

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

@@ -42,16 +42,12 @@ author: aymericzip
 
 > 开发者常犯的一个误解是认为 `next-intl` 是 `react-intl` 的 Next.js 版本。事实并非如此, `next-intl` 由 [Amann](https://github.com/amannn) 维护，而 `react-intl` 由 [FormatJS](https://github.com/formatjs/formatjs) 维护。
 
----
-
 ## 简而言之
 
 - **next-intl** - 轻量级、直接的消息格式化，具有扎实的 Next.js 支持。通常采用集中式目录；开发体验简单，但安全性和大规模维护主要依赖于你自己。
 - **next-i18next** - i18next 的 Next.js 版本。生态系统成熟，支持通过插件（例如 ICU）扩展功能，但配置可能较为冗长，且随着项目增长目录趋向集中化。
 - **Intlayer** - 面向组件的 Next.js 内容模型，**严格的 TS 类型检查**，**构建时校验**，**摇树优化**，**内置中间件和 SEO 辅助工具**，可选的**可视化编辑器/CMS**，以及**AI 辅助翻译**。
 
----
-
 | Library                | GitHub Stars                                                                                                                                                                     | Total Commits                                                                                                                                                                        | Last Commit                                                                                                                                           | First Version | NPM Version                                                                                                         | NPM Downloads                                                                                                                  |
 | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `aymericzip/intlayer`  | [![GitHub Repo stars](https://img.shields.io/github/stars/aymericzip/intlayer?style=for-the-badge&label=%E2%AD%90%20stars)](https://github.com/aymericzip/intlayer/stargazers)   | [![GitHub commit activity](https://img.shields.io/github/commit-activity/t/aymericzip/intlayer?style=for-the-badge&label=commits)](https://github.com/aymericzip/intlayer/commits)   | [![Last Commit](https://img.shields.io/github/last-commit/aymericzip/intlayer?style=for-the-badge)](https://github.com/aymericzip/intlayer/commits)   | April 2024    | [![npm](https://img.shields.io/npm/v/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer)         | [![npm downloads](https://img.shields.io/npm/dm/intlayer?style=for-the-badge)](https://www.npmjs.com/package/intlayer)         |
@@ -61,8 +57,6 @@ author: aymericzip
 
 > 徽章会自动更新。快照会随时间变化。
 
----
-
 ## 并排功能对比（以 Next.js 为重点）
 
 | 功能                                   | `next-intlayer` (Intlayer)                                                     | `next-intl`                                                  | `next-i18next`                                               |
@@ -88,16 +82,12 @@ author: aymericzip
 | **大型项目管理**                       | ✅ 鼓励模块化，适合设计系统                                                    | ✅ 通过配置实现模块化                                        | ✅ 通过配置实现模块化                                        |
 | **测试缺失的翻译（CLI/CI）**           | ✅ CLI: `npx intlayer content test`（适合CI的审计）                            | ⚠️ 非内置；文档建议使用 `npx @lingual/i18n-check`            | ⚠️ 非内置；依赖 i18next 工具 / 运行时 `saveMissing`          |
 
----
-
 ## 介绍
 
 Next.js 为你内置了国际化路由支持（例如区域段）。但该功能本身并不进行翻译。你仍然需要一个库来向用户呈现本地化内容。
 
 市面上有许多 i18n 库，但在 Next.js 领域，当前有三个正在获得关注：next-i18next、next-intl 和 Intlayer。
 
----
-
 ## 架构与可扩展性
 
 - **next-intl / next-i18next**：默认采用每个语言环境的**集中式目录**（在 i18next 中还包括**命名空间**）。在早期阶段效果良好，但随着耦合度上升和键值频繁变动，往往会成为一个庞大的共享区域。
@@ -105,8 +95,6 @@ Next.js 为你内置了国际化路由支持（例如区域段）。但该功能
 
 **重要原因：** 在大型代码库或设计系统架构中，**模块化内容**比单体目录更具扩展性。
 
----
-
 ## 包大小与依赖
 
 构建应用程序后，bundle 是浏览器加载以渲染页面的 JavaScript。因此，bundle 大小对于应用性能非常重要。
@@ -172,8 +160,6 @@ Next.js 为你内置了国际化路由支持（例如区域段）。但该功能
 | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
 | ![优化后的包](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true) | ![未优化的包](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle_no_optimization.png?raw=true) |
 
----
-
 ## TypeScript 与安全性
 
 <Columns>
@@ -198,12 +184,11 @@ Next.js 为你内置了国际化路由支持（例如区域段）。但该功能
 - **从你的内容生成严格类型**。**IDE 自动补全**和**编译时错误**能在部署前捕获拼写错误和缺失的键。
 
   </Column>
+
 </Columns>
 
 **重要原因：** 强类型将失败提前到**左侧**（CI/构建阶段），而非**右侧**（运行时）。
 
----
-
 ## 路由、中间件与 URL 策略
 
 <Columns>
@@ -228,12 +213,11 @@ Next.js 为你内置了国际化路由支持（例如区域段）。但该功能
 - 包含上述所有功能，外加 **i18n 中间件**（通过请求头/Cookies 进行语言环境检测）和用于生成本地化 URL 及 `<link rel="alternate" hreflang="…">` 标签的 **辅助工具**。
 
   </Column>
+
 </Columns>
 
 **重要性说明：** 减少自定义粘合层；实现跨语言环境的 **一致用户体验** 和 **干净的 SEO**。
 
----
-
 ## 服务器组件（RSC）对齐
 
 <Columns>
@@ -258,12 +242,11 @@ Next.js 为你内置了国际化路由支持（例如区域段）。但该功能
 - 支持 Next.js 13+，并通过一致的 API 和面向 RSC 的提供者平滑处理**服务器/客户端边界**，避免来回传递格式化器或 t 函数。
 
   </Column>
+
 </Columns>
 
 **重要原因：** 更清晰的思维模型，减少混合树中的边缘情况。
 
----
-
 ## 开发体验（DX）、工具链与维护
 
 <Columns>
@@ -288,6 +271,7 @@ Next.js 为你内置了国际化路由支持（例如区域段）。但该功能
 - 提供一个**免费的可视化编辑器**和**可选的CMS**（支持Git友好或外部化），以及一个**VSCode扩展**和使用您自己的提供商密钥的**AI辅助翻译**。
 
   </Column>
+
 </Columns>
 
 **重要原因：** 降低运营成本，缩短开发者与内容作者之间的反馈周期。
@@ -798,8 +782,6 @@ const ClientComponentExample = () => {
   - **next-intl** 灵活；根据配置加载消息。
   - **Intlayer** 将内容存储在 TS/JS 字典中，并通过键解析。
 
----
-
 ### 在服务器组件中的使用
 
 我们以一个 UI 组件为例。该组件是一个服务器组件，并且应该能够作为客户端组件的子组件插入。（页面（服务器组件）-> 客户端组件 -> 服务器组件）。由于该组件可以作为客户端组件的子组件插入，因此它不能是异步的。
@@ -897,7 +879,7 @@ const ServerComponent = ({ count }: { count: number }) => {
 开发者经常忘记正确地在不同语言环境中引用他们的页面。
 
 <Tabs defaultTab="next-intl" group='techno'>
- 
+
   <Tab label="next-i18next" value="next-i18next">
 
 ```ts fileName="i18n.config.ts"
@@ -1158,8 +1140,6 @@ export default robots;
 
 > Intlayer 提供了一个 `getMultilingualUrls` 函数，用于为您的站点地图生成多语言 URL。
 
----
-
 ### 本地化路由的中间件
 
 <Tabs defaultTab="next-intl" group='techno'>
@@ -1277,9 +1257,8 @@ export const config = {
 - **集成工具**：利用内置的路由、SEO 辅助工具和可视化编辑器支持。
 
   </Tab>
-</Tabs>
 
----
+</Tabs>
 
 ## 胜者是…
 
@@ -1307,6 +1286,7 @@ export const config = {
 - 为现代 Next.js 构建，具有模块化内容、类型安全、工具支持和更少的样板代码。如果你重视**组件范围的内容**、**严格的 TypeScript**、**构建时保证**、**摇树优化**，以及**内置的**路由/SEO/编辑器工具, 尤其是针对**Next.js 应用路由器**、设计系统和**大型模块化代码库**。
 
   </Column>
+
 </Columns>
 
 如果你偏好最小化设置并且能接受一些手动连接，next-intl 是一个不错的选择。如果你需要所有功能且不介意复杂性，next-i18next 也适用。但如果你想要一个现代、可扩展、模块化且带有内置工具的解决方案，Intlayer 旨在为你开箱即用提供这些功能。
@@ -1321,8 +1301,6 @@ GitHub 星标是衡量项目受欢迎程度、社区信任度和长期相关性
 
 [![星标历史图表](https://api.star-history.com/chart?repos=i18next/next-i18next%2Camannn/next-intl%2Caymericzip/intlayer&type=date&legend=top-left)](https://www.star-history.com/#i18next/next-i18next&amannn/next-intl&aymericzip/intlayer)
 
----
-
 ## 结论
 
 所有三个库在核心本地化方面都取得了成功。区别在于，在**现代 Next.js**中实现一个健壮且可扩展的设置，你需要付出**多少工作量**：

package/blog/zh/nextjs-multilingual-seo-comparison.md

@@ -26,8 +26,6 @@ author: aymericzip
 
 在这篇博客中，我们将探讨 **为什么国际化（i18n）是 SEO 的超级力量**，以及如何在 Next.js 中使用 `next-intl`、`next-i18next` 和 `Intlayer` 正确实现它。
 
----
-
 ## 为什么要做 SEO 和国际化
 
 添加语言不仅仅是为了用户体验（UX）。它也是提升 **自然流量可见性** 的强大杠杆。原因如下：
@@ -37,8 +35,6 @@ author: aymericzip
 3. **更好的用户体验：** 访客能够立即访问到你网站的正确语言版本。
 4. **竞争优势：** 很少有网站能很好地实现多语言SEO，这意味着你可以脱颖而出。
 
----
-
 ## Next.js 多语言SEO最佳实践
 
 以下是每个多语言应用都应该实施的检查清单：
@@ -57,8 +53,6 @@ author: aymericzip
 
 这些都是简单的步骤, 但跳过它们可能会让你失去可见性。
 
----
-
 ## 实现示例
 
 开发者经常忘记在不同语言环境中正确引用他们的页面，因此让我们看看使用不同库时这是如何实际操作的。
@@ -345,14 +339,10 @@ export default robots;
   </Tab>
 </Tabs>
 
----
-
 ## 使用 Intlayer SEO Scanner 审核您的网站
 
 为了确保您的多语言应用程序得到完美优化，我们建议使用 [Intlayer SEO Scanner](https://intlayer.org/i18n-seo-scanner)。这是一款专门用于多语言网站检查的工具，可帮助您识别所有本地化页面中缺失的 hreflang 标签、断开的链接以及其他 SEO 问题。
 
----
-
 ## 结论
 
 在 Next.js 中正确处理国际化（i18n）不仅仅是翻译文本，更是确保搜索引擎和用户能够准确识别并访问您内容的正确版本。

package/blog/zh/react-i18next_vs_react-intl_vs_intlayer.md

@@ -37,16 +37,12 @@ author: aymericzip
 
 > **简而言之**：这三者都能实现 React 应用的本地化。如果您需要**组件范围的内容**、**严格的 TypeScript 类型**、**构建时缺失键检查**、**支持 Tree-shaking 的字典**，以及内置的编辑工具（可视化编辑器/CMS + 可选的 AI 翻译），那么 **Intlayer** 是模块化 React 代码库中最完整的选择。
 
----
-
 ## 高层定位
 
 - **react-intl** - 以 ICU 为先，符合标准的格式化（日期/数字/复数），拥有成熟的 API。目录通常是集中管理的；键的安全性和构建时验证主要由你负责。
 - **react-i18next** - 极其流行且灵活；支持命名空间、检测器和许多插件（ICU、后端等）。功能强大，但随着项目规模扩大，配置可能变得复杂。
 - **Intlayer** - 面向组件的 React 内容模型，**严格的 TS 类型**，**构建时检查**，**支持 Tree-shaking**，以及 **可视化编辑器/CMS** 和 **AI 辅助翻译**。兼容 React Router、Vite、CRA 等。
 
----
-
 ## 功能矩阵（React 重点）
 
 | 功能                                   | `react-intlayer` (Intlayer)                                                              | `react-i18next` (i18next)                                      | `react-intl` (FormatJS)                            |
@@ -71,8 +67,6 @@ author: aymericzip
 | **清除未使用内容**                     | ✅ 是的，按词典在构建时                                                                  | ❌ 否，仅通过手动命名空间分割                                  | ❌ 否，所有声明的消息都会被打包                    |
 | **大型项目管理**                       | ✅ 鼓励模块化，适合设计系统                                                              | ⚠️ 需要良好的文件管理                                          | ⚠️ 中央目录可能变得庞大                            |
 
----
-
 ## 深度比较
 
 ### 1) 架构与可扩展性
@@ -82,8 +76,6 @@ author: aymericzip
 
 **重要原因：** 模块化内容反映模块化 UI。当翻译与其所属组件共存时，大型 React 代码库会保持更整洁。
 
----
-
 ### 2) TypeScript 与安全性
 
 - **react-intl**：类型定义扎实，但**没有自动键类型**；你需要自己强制安全模式。
@@ -92,8 +84,6 @@ author: aymericzip
 
 **重要原因：** 将失败“左移”（到构建/CI阶段）可以减少生产环境问题并加快开发者反馈循环。
 
----
-
 ### 3) 缺失翻译处理
 
 - **react-intl / react-i18next**：默认使用**运行时回退**（键回显或默认语言）。您可以添加代码检查/插件，但构建时不保证检测。
@@ -101,8 +91,6 @@ author: aymericzip
 
 **重要原因：** CI 在缺失字符串时失败，防止“神秘的英文”泄漏到非英文界面中。
 
----
-
 ### 4) 丰富内容与格式化
 
 - **react-intl**：对复数、选择、日期/数字和消息组合提供出色的 **ICU** 支持。可以使用 JSX，但思维模型仍以消息为中心。
@@ -111,8 +99,6 @@ author: aymericzip
 
 **重要原因：** 当库能够干净地支持 React 节点时，处理复杂的 UI 文本（链接、加粗部分、内联组件）会更加轻松。
 
----
-
 ### 5) 性能与加载行为
 
 - **react-intl / react-i18next**：您通常需要手动管理**目录拆分**和**懒加载**（命名空间/动态导入）。这种方式有效但需要严格的规范。
@@ -120,8 +106,6 @@ author: aymericzip
 
 **重要性说明：** 更小的包体积和更少的未使用字符串能提升启动和导航性能。
 
----
-
 ### 6) 开发体验（DX）、工具链与维护
 
 - **react-intl / react-i18next**：拥有广泛的社区生态系统；对于编辑工作流，通常采用外部本地化平台。
@@ -129,16 +113,12 @@ author: aymericzip
 
 **重要原因：** 内置工具缩短了开发者与内容作者之间的反馈周期--减少了胶水代码，降低了对第三方依赖的需求。
 
----
-
 ## 何时选择哪种方案？
 
 - 如果您需要**以 ICU 为优先**的消息格式化，且希望使用简洁、符合标准的 API，并且您的团队能够手动维护目录和安全检查，**请选择 react-intl**。
 - 如果您需要**i18next 生态系统的广泛支持**（检测器、后端、ICU 插件、集成等），并且愿意接受更多配置以获得更高灵活性，**请选择 react-i18next**。
 - **选择 Intlayer** 如果你重视 **组件范围的内容管理**、**严格的 TypeScript 类型检查**、**构建时保证**、**摇树优化**，以及 **开箱即用** 的编辑工具 -- 尤其适用于 **大型、模块化** 的 React 应用。
 
----
-
 ## 实用迁移建议（react-intl / react-i18next → Intlayer）
 
 - **渐进迁移**：从一个功能或路由开始；在过渡期间并行保留旧版目录。
@@ -146,8 +126,6 @@ author: aymericzip
 - **启用严格检查**：让构建时错误提前暴露缺失的键/语言，便于 CI 早期发现。
 - **测量包体积**：预期未使用的字符串被剔除后包体积会减小。
 
----
-
 ## GitHub STARs
 
 GitHub stars 是项目受欢迎程度、社区信任度和长期相关性的强有力指标。虽然不是技术质量的直接衡量标准，但它们反映了有多少开发者认为该项目有用、关注其进展，以及可能会采用它。对于评估项目价值，stars 有助于比较不同替代方案的吸引力，并提供对生态系统增长的洞察。

package/blog/zh/transform_existing_nextjs_app_using_compiler.md

@@ -0,0 +1,293 @@
+---
+createdAt: 2026-01-10
+updatedAt: 2026-09-06
+title: "如何在事后为现有 Next.js 应用程序实现多语言（i18n 指南 2026）"
+description: "2026 年现有 Next.js 应用的多语言 (i18n) 改造指南。无需繁琐重构，借助 Intlayer 体验自动内容提取、AI 翻译与高性能路由。"
+keywords:
+  - Next.js i18n
+  - 国际化
+  - 翻译现有 Next.js 应用
+  - Next.js 16
+  - Intlayer
+  - 多语言
+  - React i18n
+  - 编译器
+  - AI 翻译
+  - SEO
+slugs:
+  - blog
+  - transform-existing-nextjs-app-into-multilingual-app
+applicationTemplate: https://github.com/aymericzip/intlayer-next-no-lolale-path-template
+youtubeVideo: https://www.youtube.com/watch?v=e_PPG7PTqGU
+history:
+  - version: 9.4.0
+    date: 2026-08-22
+    changes: "Update to Next.js >= 9.4.0 architecture"
+  - version: 8.9.0
+    date: 2026-05-04
+    changes: "Update Solid useIntlayer API usage to direct property access"
+  - version: 8.2.0
+    date: 2026-03-09
+    changes: "Update compiler options, add FilePathPattern support"
+  - version: 8.1.6
+    date: 2026-02-23
+    changes: "Initial release"
+author: aymericzip
+---
+
+# 如何在事后为现有 Next.js 应用程序实现多语言（i18n 指南 2026）
+
+从项目第一天起就为 Next.js 添加国际化 (i18n) 相对轻松。但如果您的单语言 Next.js 应用程序已经上线成熟，事后需要将其改造成多语言应用，该如何处理？
+
+使用传统库（如 `next-intl` 或 `next-i18next`）往往是一场噩梦：
+
+- 在数百个 JSX/TSX 文件中手动搜索硬编码的文本字符串。
+- 手动创建嵌套的 JSON 字典并编造任意翻译键名（如 `pages.dashboard.header.title` 等）。
+- 用繁琐的 hook（如 `t('...')`）替换原有文字。
+- 将整个 `app/` 目录重构为 `app/[locale]/...`，导致现有路由、书签和搜索引擎收录失效。
+
+在 2026 年，您不再需要大动干戈重写代码。借助 **Intlayer**，您可以通过自动化提取、AI 翻译与非侵入式路由，在数分钟内为现有 Next.js 应用无缝接入国际化。
+
+> 需要查看针对 Next.js 16 App Router 的完整详细分步技术指南？请查阅我们的专属文档：[使用 Intlayer 翻译 Next.js 16](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_16.md)。
+
+## 目录
+
+<TOC/>
+
+## 改造难题：为什么现有应用实现国际化如此痛苦？
+
+对现有 Next.js 应用程序进行国际化改造时，开发者常面临三大障碍：
+
+1. **侵入性过高**：手动将字符串提取到 JSON 字典几乎需要改动所有组件文件，产生巨大的代码变更与回归风险。
+2. **强制路由重构**：传统 i18n 库通常强制将根布局与页面移入动态 `[locale]` 路径（如 `/app/[locale]/page.tsx`）。
+3. **翻译繁琐重复**：提取字符串后，维护几十种语言的字典需要反复复制粘贴或购买昂贵的本地化服务。
+
+Intlayer 从架构层面上通过**编译器智能提取**、**声明式字典**与**灵活路由**彻底解决了这些问题。
+
+## 自动化内容提取（告别手动搜寻字符串）
+
+### 选项 A：CLI 提取工具 (`npx intlayer extract`)
+
+直接在您的项目代码中运行 Intlayer 提取命令：
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer extract
+```
+
+```bash packageManager="bun"
+bunx intlayer extract
+```
+
+该命令会分析 React 组件，提取可见文本，并在组件同级目录下自动生成声明式内容文件（`.content.ts`），保持代码整洁与类型安全。
+
+### 选项 B：Intlayer 编译器（构建时自动提取）
+
+启用 Intlayer 编译器后，您只需像往常一样在组件中编写默认语言的纯文本。在构建时，编译器会自动提取文本并注入本地化内容：
+
+```tsx fileName="src/app/page.tsx"
+// Write normal React code. The compiler extracts the text automatically
+export default function HomePage() {
+  return (
+    <section>
+      <h1>Welcome to our platform</h1>
+      <p>Start exploring our modern features today.</p>
+    </section>
+  );
+}
+```
+
+在底层，Intlayer 会自动构建字典并将组件与本地化内容关联，彻底免去手动重构的繁琐步骤。
+
+在这种情况下，它将生成包含以下内容的 `src/app/page.content.ts` 文件：
+
+```typescript fileName="src/app/page.content.ts"
+import { Dictionary } from "intlayer";
+
+const content = {
+  key: "home-page",
+  content: {
+    welcomeToOurPlatform: t({ en: "Welcome to our platform" }),
+    startExploringOurModernFeaturesToday: t({
+      en: "Start exploring our modern features today.",
+    }),
+  },
+};
+
+export default content;
+```
+
+## 借助您喜爱的 LLM 进行 AI 自动化翻译
+
+提取完内容后，无需人工逐句翻译。Intlayer 内置 AI 翻译命令行，支持使用您自己的 OpenAI、Anthropic、DeepSeek 或 Mistral API 密钥：
+
+```bash packageManager="npm"
+npx intlayer fill
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer fill
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer fill
+```
+
+```bash packageManager="bun"
+bunx intlayer fill
+```
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH, Locales.GERMAN],
+    defaultLocale: Locales.ENGLISH,
+  },
+  ai: {
+    provider: "openai",
+    model: "gpt-4o-mini",
+    apiKey: process.env.OPENAI_API_KEY,
+    applicationContext: "面向团队协作与生产力的 SaaS 控制台",
+  },
+};
+
+export default config;
+```
+
+运行 `npx intlayer fill` 后，会自动为您配置的所有语言在 `.content.ts` 声明文件中填充翻译：
+
+```typescript fileName="src/app/page.content.ts"
+import { Dictionary } from "intlayer";
+
+const content = {
+  key: "home-page",
+  content: {
+    welcomeToOurPlatform: t({
+      en: "Welcome to our platform",
+      fr: "Bienvenue sur notre plateforme",
+      es: "Bienvenido a nuestra plataforma",
+      zh: "欢迎来到我们的平台",
+    }),
+    startExploringOurModernFeaturesToday: t({
+      en: "Start exploring our modern features today.",
+      fr: "Découvrez nos fonctionnalités modernes dès aujourd'hui.",
+      es: "Comience a explorar nuestras funciones modernas hoy.",
+      zh: "立即开始体验我们的现代化功能。",
+    }),
+  },
+};
+
+export default content;
+```
+
+由于 Intlayer 向 LLM 提供了高层级的 `applicationContext`，因此生成的翻译能够比传统自动化工具更好地保留技术细节、品牌语调和语法语境。
+
+在部署到生产环境之前，验证是否存在遗漏的文本：
+
+```bash
+npx intlayer test
+```
+
+## 添加多语言路由且不破坏现有 URL
+
+Intlayer 提供多种路由开箱即用策略：
+
+- **查询参数 / Cookie 模式 (`search-params`)**：保持原有的 `/app/page.tsx` 结构，无需迁移到 `[locale]` 目录。
+- **前缀模式 (`prefix` / `prefix-all-locales`)**：当您准备好采用对 SEO 友好的路径路由（如 `/zh/dashboard`）时，Intlayer 通过代理轻松支持。
+
+在数秒内完成 Next.js 集成配置：
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { withIntlayer } from "next-intlayer/server";
+
+const nextConfig: NextConfig = {/* Your existing Next.js config */};
+
+export default withIntlayer(nextConfig);
+```
+
+使用 `IntlayerProvider` 包裹您的根布局：
+
+```tsx fileName="src/app/layout.tsx"
+import type { ReactNode } from "react";
+import { IntlayerProvider } from "next-intlayer";
+import { getLocale } from "next-intlayer/server";
+import { getHTMLTextDir } from "intlayer";
+
+export default async function RootLayout({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body>
+        <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## 多语言 SEO
+
+自动生成多语言元数据和 `hreflang` 标签，提升全球搜索可见度：
+
+```tsx fileName="src/app/page.tsx"
+import type { Metadata } from "next";
+import { getLocale } from "next-intlayer/server";
+import { getIntlayer } from "intlayer";
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const locale = await getLocale();
+  const content = getIntlayer("home-page-metadata", locale);
+
+  return {
+    title: content.title,
+    description: content.description,
+  };
+};
+```
+
+## 深入探索：准备好分步实践了吗？
+
+本指南为您提供了在 2026 年快速改造现有 Next.js 应用的高级概览。若需查阅中间件配置、静态生成 (`generateStaticParams`) 及服务器组件的完整分步指南，请访问：
+
+👉 **[使用 Intlayer 翻译 Next.js 16 完整指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_16.md)**
+
+## 常见问题解答 (FAQ)
+
+<FAQ>
+
+<Question title="我是否可以在不将文件移动到 app/[locale] 的情况下实现多语言？">
+
+可以。Intlayer 支持 `routing.mode: "search-params"` 以及基于 Cookie / Header 的语言检测，完整保留现有目录与 URL。
+
+</Question>
+<Question title="我必须手动替换代码中的所有硬编码字符串吗？">
+
+不需要。使用 `npx intlayer extract` 或 Intlayer 编译器即可自动提取和声明内容。
+
+</Question>
+<Question title="相比 next-intl，Intlayer 是如何减少打包体积的？">
+
+Intlayer 采用按组件声明与构建时宏优化，客户端只下载当前页面组件所需的内容片段。
+
+</Question>
+<Question title="可以使用 AI 自动将现有组件翻译为多种语言吗？">
+
+可以。运行 `npx intlayer fill` 即可自动连接 AI 服务生成上下文相关的缺失翻译。
+
+</Question>
+</FAQ>