@intlayer/docs 9.4.4 → 9.5.0

package/docs/zh/intlayer_with_nextjs_16.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-12-06
-updatedAt: 2026-08-30
+updatedAt: 2026-09-08
 title: "Next.js 16 i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Next.js 16 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -41,7 +41,7 @@ author: aymericzip
 <iframe title="Next.js 最佳 i18n 解决方案？探索 Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/e_PPG7PTqGU?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
   </Tab>
-  <Tab label="代码" value="code">
+  <Tab label="代码 (带语言路径)" value="code-locale-path">
 
 <iframe
   src="https://ide.intlayer.org/aymericzip/intlayer-next-16-template?file=intlayer.config.ts"
@@ -52,12 +52,23 @@ author: aymericzip
 />
 
   </Tab>
-  <Tab label="演示" value="demo">
+  <Tab label="代码 (无语言路径)" value="code-no-locale-path">
+
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-next-16-no-locale-path-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - 如何使用 Intlayer 国际化您的应用程序"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
+  <Tab label="演示 (带语言路径)" value="demo">
 
 <iframe
   src="https://intlayer-next-16-template.vercel.app"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="演示 - intlayer-next-16-template"
+  title="演示 Intlayer Next.js 16 Template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />
@@ -65,7 +76,7 @@ author: aymericzip
   </Tab>
 </Tabs>
 
-请参阅 GitHub 上的[应用模板](https://github.com/aymericzip/intlayer-next-16-template)。
+请参阅 GitHub 上的[应用模板](https://github.com/aymericzip/intlayer-next-16-template) 以及 [无语言路径的应用模板](https://github.com/aymericzip/intlayer-next-no-lolale-path-template)。
 
 ## 目录
 
@@ -75,49 +86,41 @@ author: aymericzip
 
 与 `next-intl` 或 `i18next` 等主流解决方案相比，Intlayer 是一个提供集成优化的解决方案，例如：
 
-与“next-intl”或“i18next”等主要解决方案相比，Intlayer是一个具有集成优化的解决方案，例如：
-
 <AccordionGroup>
 <Accordion header="完整的 Next.js 覆盖">
 
 Intlayer 经过优化，可以与 **服务器组件** 配合使用，以实现高效渲染，并且与 [**Turbopack**](https://nextjs.org/docs/architecture/turbopack) 完全兼容。它不会阻止静态渲染，并提供中间件以及扩展国际化 (i18n) 所需的所有功能。
 
 > Intlayer 兼容 Next.js 12、13、14、15 和 16。如果您使用 Next.js Pages Router，可以参考此[指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_page_router.md)。
-> 区域设置路由对于 SEO、Bundle 大小和性能很有用。如果不需要，可以参考这个[指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_no_locale_path.md)。
+> 语言路由对 SEO、打包体积和性能非常有用。本指南同时支持并介绍了带语言路径和不带语言路径的两种配置。
 > 对于带有 App Router 的 Next.js 12、13、14 和 15，请参阅此[指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nextjs_14.md)。
 
 </Accordion>
-
 <Accordion header="捆绑尺寸">
 
 不要将大量 JSON 文件加载到页面中，而只需加载必要的内容。 Intlayer 有助于**将捆绑包和页面大小减少多达 50%**。
 
 </Accordion>
-
 <Accordion header="可维护性">
 
 确定应用程序内容的范围**有利于大型应用程序的维护**。您可以复制或删除单个功能文件夹，而无需承担检查整个内容代码库的精神负担。此外，Intlayer 具有**完全类型化 (fully typed)**，以确保您的内容的准确性。
 
 </Accordion>
-
 <Accordion header="人工智能代理">
 
 共置内容**减少大型语言模型 (LLM) 所需的上下文**。 Intlayer 还附带了一套工具，例如用于测试缺失翻译的 **CLI**、**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**、**[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** 和 **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**，使 AI 代理的开发者体验 (DX) 更加流畅。
 
 </Accordion>
-
 <Accordion header="自动化">
 
 使用您选择的法学硕士，通过自动化在 CI/CD 管道中进行翻译，而费用由您的 AI 提供商承担。 Intlayer 还提供了一个**编译器**来自动提取内容，以及一个[网络平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)来帮助**在后台翻译**。
 
 </Accordion>
-
 <Accordion header="表现">
 
 将大量 JSON 文件连接到组件可能会导致性能和反应性问题。 Intlayer 可在构建时 (build time)优化您的内容加载。
 
 </Accordion>
-
 <Accordion header="无需开发即可扩展">
 
 Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)**和一个**[完整的 CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** 来帮助您管理多语言内容**实时**，与译员、文案人员和其他团队成员无缝协作。内容可以本地和/或远程存储。
@@ -125,12 +128,9 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 </Accordion>
 </AccordionGroup>
 
----
-
 ## 在 Next.js 应用程序中设置 Intlayer 的分步指南
 
 <Steps>
-
 <Step number={1} title="安装依赖项">
 
 使用 npm 安装必要的包：
@@ -180,10 +180,16 @@ bun add intlayer next-intlayer
   将 Intlayer 与 Next.js 集成的包。它为 Next.js 国际化提供上下文提供者和钩子。此外，它还包括用于将 Intlayer 与 [Webpack](https://webpack.js.org/) 或 [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack) 集成的 Next.js 插件，以及用于检测用户首选语言环境、管理 cookie 和处理 URL 重定向的代理。
 
 </Step>
-
 <Step number={2} title="配置您的项目">
 
-这是我们将创建的最终结构：
+选择您的应用程序是使用本地化 URL 路径（例如 `/zh/about`、`/en/about`），还是在路径中不包含语言段的情况下提供内容（例如 `/about`，通过 Cookie、请求头或查询参数检测语言）。
+
+<Tabs group="routing-mode">
+<Tab label="带语言路径" value="with-locale-path">
+
+### 架构
+
+在此架构中，所有本地化页面都嵌套在 `[locale]` 动态路由段下。推荐将此方法用于 SEO 和静态渲染，因为每种语言都有专用的独立 URL：
 
 ```bash
 .
@@ -209,9 +215,9 @@ bun add intlayer next-intlayer
 └── tsconfig.json
 ```
 
-> 如果您不需要语言环境路由，intlayer 可以用作简单的提供者/钩子。有关更多详细信息，请参见[此指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_no_locale_path.md)。
+### 配置
 
-创建一个配置文件来配置您的应用程序语言：
+创建 `intlayer.config.ts` 配置文件以声明您的应用程序支持的语言：
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -226,15 +232,76 @@ const config: IntlayerConfig = {
     ],
     defaultLocale: Locales.ENGLISH,
   },
+  routing: {
+    mode: "prefix-no-default", // 或 `prefix-all`
+  },
+};
+
+export default config;
+```
+
+</Tab>
+<Tab label="不带语言路径" value="without-locale-path">
+
+### 架构
+
+在此架构中，路由在 URL 路径中不包含动态 `[locale]` 段。所有页面直接位于 `src/app/` 下，并通过 Cookie、请求头或查询参数确定语言。这非常适合仪表板、内部工具或身份验证后的应用程序：
+
+```bash
+.
+├── src
+│   ├── app
+│   │   ├── layout.tsx
+│   │   ├── page.content.ts
+│   │   └── page.tsx
+│   ├── components
+│   │   ├── clientComponentExample
+│   │   │   ├── client-component-example.content.ts
+│   │   │   └── ClientComponentExample.tsx
+│   │   ├── localeSwitcher
+│   │   │   ├── localeSwitcher.content.ts
+│   │   │   └── LocaleSwitcher.tsx
+│   │   └── serverComponentExample
+│   │       ├── server-component-example.content.ts
+│   │       └── ServerComponentExample.tsx
+│   └── proxy.ts
+├── intlayer.config.ts
+├── next.config.ts
+├── package.json
+└── tsconfig.json
+```
+
+### 配置
+
+将 `routing.mode` 属性设置为 `"search-params"`（例如 `/about?locale=zh`）或 `"no-prefix"`，以在没有路径前缀的情况下提供内容：
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // 你的其他语言
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    mode: "search-params", // 或 `no-prefix` - 用于中间件检测
+  },
 };
 
 export default config;
 ```
 
+</Tab>
+</Tabs>
+
 > 通过此配置文件，您可以设置本地化 URL、代理重定向、cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
 </Step>
-
 <Step number={3} title="在 Next.js 配置中集成 Intlayer">
 
 配置您的 Next.js 设置以使用 Intlayer：
@@ -277,9 +344,11 @@ export default withIntlayer(nextConfig);
 > ```
 
 </Step>
-
 <Step number={4} title="定义动态语言环境路由">
 
+<Tabs group="routing-mode">
+<Tab label="带语言路径" value="with-locale-path">
+
 从 `RootLayout` 中删除所有内容，并将其替换为以下代码：
 
 ```tsx {3} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
@@ -374,8 +443,103 @@ export default LocaleLayout;
 
 > Intlayer 与 `export const dynamic = 'force-static';` 配合使用，以确保为所有语言环境预构建页面。
 
-</Step>
+</Tab>
+<Tab label="不带语言路径" value="without-locale-path">
+
+在没有语言路径的架构中，不存在 `[locale]` 目录。直接配置 `src/app/layout.tsx` 从请求上下文中读取语言，并使用 `IntlayerProvider` 包裹您的应用程序：
+
+<Tabs>
+ <Tab label='Intlayer >=9.4' value='>=9.4'>
+
+```tsx {5} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+import { getHTMLTextDir, getIntlayer } from "intlayer";
+import { getLocale, IntlayerProvider } from "next-intlayer/server";
+export { generateStaticParams } from "next-intlayer";
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const locale = await getLocale();
+  const { title, description, keywords } = getIntlayer("metadata", locale);
+
+  return {
+    title,
+    description,
+    keywords,
+  };
+};
 
+const RootLayout = async ({
+  children,
+}: Readonly<{
+  children: ReactNode;
+}>) => {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+      </body>
+    </html>
+  );
+};
+
+export default RootLayout;
+```
+
+> 单个 `IntlayerProvider` 覆盖树的两个部分：它为服务器钩子读取的请求作用域服务器上下文提供种子，并挂载客户端提供程序，以便客户端组件接收相同的区域设置。
+
+ </Tab>
+ <Tab label='Intlayer <9.4' value='<9.4'>
+
+```tsx {3} fileName="src/app/layout.tsx" codeFormat={["typescript", "esm"]}
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+import { IntlayerProvider, LocalPromiseParams } from "next-intlayer";
+import { getHTMLTextDir, getIntlayer } from "intlayer";
+import { getLocale } from "next-intlayer/server";
+export { generateStaticParams } from "next-intlayer";
+
+export const generateMetadata = async (): Promise<Metadata> => {
+  const locale = await getLocale();
+  const { title, description, keywords } = getIntlayer("metadata", locale);
+
+  return {
+    title,
+    description,
+    keywords,
+  };
+};
+
+const RootLayout = async ({
+  children,
+}: Readonly<{
+  children: ReactNode;
+}>) => {
+  const locale = await getLocale();
+
+  return (
+    <html lang={locale} dir={getHTMLTextDir(locale)}>
+      <body>
+        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
+      </body>
+    </html>
+  );
+};
+
+export default RootLayout;
+```
+
+ </Tab>
+</Tabs>
+
+</Tab>
+</Tabs>
+
+</Step>
 <Step number={5} title="声明您的内容">
 
 创建并管理您的内容声明以存储翻译：
@@ -423,7 +587,6 @@ export default pageContent;
 > 有关更多详细信息，请参阅[内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
 
 </Step>
-
 <Step number={6} title="在代码中利用内容">
 
 在整个应用程序中访问你的内容字典：
@@ -461,7 +624,7 @@ export default Page;
 ```
 
 - **`IntlayerProvider`** 在 locale layout 中挂载一次。它向服务器和客户端组件提供 locale，因此页面不再需要自己包装。
-- 服务器 hooks 按以下顺序解析 locale：调用站点传递的 locale，然后是由提供者种子化的服务器上下文，然后是请求携带的 locale（由 Intlayer 代理设置的 `x-intlayer-locale` header，然后是 locale cookie）。最后一步是保持内容在客户端导航中正确的原因，在客户端导航中只重新渲染页面段，而 layout——以及它的 provider——不会重新运行。
+- 服务器 hooks 按以下顺序解析 locale：调用站点传递的 locale，然后是由提供者种子化的服务器上下文，然后是请求携带的 locale（由 Intlayer 代理设置的 `x-intlayer-locale` header，然后是 locale cookie）。最后一步是保持内容在客户端导航中正确的原因，在客户端导航中只重新渲染页面段，而 layout, , 以及它的 provider, , 不会重新运行。
 
 在整个应用程序中访问您的内容字典：
 
@@ -570,10 +733,10 @@ export const ServerComponentExample: FC = () => {
 
 > 如果您想在 `string` 属性中使用您的内容，例如 `alt`、`title`、`href`、`aria-label` 等，您必须调用该函数的值，如下所示：
 
-> ```html
-> <img src="{content.image.src.value}" alt="{content.image.value}" />
-> <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
-> <img src="{String(content.image.src)}" alt="{String(content.image)}" />
+> ```tsx
+> <img src={content.image.src.value} alt={content.image.value} />
+> <img src={content.image.src.toString()} alt={content.image.toString()} />
+> <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
 > 要了解有关 `useIntlayer` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useIntlayer.md)。
@@ -581,7 +744,6 @@ export const ServerComponentExample: FC = () => {
 > 如果您的应用程序已经存在，您可以结合使用 [Intlayer 编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 和 [提取命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 在一秒钟内转换成干个组件。
 
 </Step>
-
 <Step number={7} title="配置代理进行语言环境检测" isOptional={true}>
 
 设置代理以检测用户首选的语言环境：
@@ -609,7 +771,6 @@ export const proxy = multipleProxies([intlayerProxy, customProxy]);
 ```
 
 </Step>
-
 <Step number={8} title="元数据的国际化" isOptional={true}>
 
 在您想要国际化元数据（例如页面标题）的情况下，您可以使用 Next.js 提供的 `generateMetadata` 函数。在其中，您可以从 `getIntlayer` 函数中检索内容来翻译您的元数据。
@@ -712,7 +873,6 @@ export const generateMetadata = async ({
 > 在 [Next.js 官方文档](https://nextjs.org/docs/app/building-your-application/optimizing/metadata) 上了解更多关于元数据优化的信息。
 
 </Step>
-
 <Step number={9} title="sitemap.xml 和 robots.txt 的国际化" isOptional={true}>
 
 要对您的 `sitemap.xml` 和 `robots.txt` 进行国际化，您可以使用 Intlayer 提供的 `getMultilingualUrls` 函数。此函数允许您为站点地图生成多语言 URL。
@@ -777,7 +937,6 @@ export default robots;
 > 在 [Next.js 官方文档](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap) 上了解更多关于站点地图优化的信息。在 [Next.js 官方文档](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/robots) 上了解更多关于 robots.txt 优化的信息。
 
 </Step>
-
 <Step number={10} title="更改内容的语言" isOptional={true}>
 
 要在 Next.js 中更改内容的语言，推荐的方法是使用 `Link` 组件将用户重定向到相应的本地化页面。`Link` 组件支持页面预取，这有助于避免全页面重新加载。
@@ -864,7 +1023,6 @@ return <button onClick={() => setLocale(Locales.FRENCH)}>更改为法语</button
 > - [`aria-current` 属性](https://developer.mozilla.org/zh-CN/docs/Web/Accessibility/ARIA/Attributes/aria-current)
 
 </Step>
-
 <Step number={11} title="创建本地化链接组件" isOptional={true}>
 
 为了确保您的应用程序导航尊重当前语言环境，您可以创建一个自定义的 `Link` 组件。此组件会自动为内部 URL 添加当前语言的前缀。例如，当讲法语的用户点击“关于”页面的链接时，他们会被重定向到 `/fr/about` 而不是 `/about`。
@@ -934,7 +1092,6 @@ export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
 通过在整个应用程序中集成此 `Link` 组件，您可以维持连贯且具有语言意识的用户体验，同时还能从改进的 SEO 和可用性中获益。
 
 </Step>
-
 <Step number={12} title="在 Server Actions 中获取当前语言环境" isOptional={true}>
 
 如果您在 Server Action 中需要活动语言环境（例如，为了本地化电子邮件或运行语言环境感知逻辑），请从 `next-intlayer/server` 调用 `getLocale`：
@@ -961,7 +1118,6 @@ export const myServerAction = async () => {
 > 这确保了根据可用上下文选择最合适的语言环境。
 
 </Step>
-
 <Step number={13} title="优化您的Bundle 大小" isOptional={true}>
 
 使用 `next-intlayer` 时，默认情况下每个页面的包中都会包含字典。为了优化Bundle 大小，Intlayer 提供了一个可选的 SWC 插件，该插件可以使用宏智能地替换 `useIntlayer` 调用。这确保了字典仅包含在实际使用它们的页面的包中。
@@ -991,7 +1147,6 @@ bun add @intlayer/swc --dev
 > 注意：如果您将选项设置为 `importMode: 'dynamic'` 或 `importMode: 'fetch'`（在 `dictionary` 配置中），它将依赖于 Suspense，因此您必须将 `useIntlayer` 调用包装在 `Suspense` 边界中。这意味着，您将无法直接在页面/布局组件的顶层使用 `useIntlayer`。
 
 </Step>
-
 <Step number={14} title="提取组件内容" isOptional={true}>
 
 如果您有现有的代码库，转换数千个文件可能会非常耗时。
@@ -1055,8 +1210,6 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel 编译器'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```
@@ -1112,6 +1265,14 @@ bun run build # Or bun run dev
 
 ### 在 Turbopack 上监视字典更改
 
+<Tabs>
+ <Tab label='Intlayer >=9.5' value='intlayer>=9.5'>
+
+从 Intlayer v9.5 开始，`withIntlayer` 会自行启动 content watcher，无需额外设置。
+
+ </Tab>
+ <Tab label='Intlayer <9.5' value='intlayer<9.5'>
+
 当使用 Turbopack 作为您的开发服务器并运行 `next dev` 命令时，默认情况下不会自动检测字典更改。
 
 出现这种限制是因为 Turbopack 无法并行运行 webpack 插件以监视内容文件中的更改。要解决此问题，您需要使用 `intlayer watch` 命令同时运行开发服务器和 Intlayer 构建监视器。
@@ -1128,6 +1289,8 @@ bun run build # Or bun run dev
 
 > 如果您使用的是 next-intlayer@<=6.x.x，则需要保留 `--turbopack` 标志以使 Next.js 16 应用程序在 Turbopack 下正常工作。我们建议使用 next-intlayer@>=7.x.x 以避免此限制。
 
+ </Tab>
+</Tabs>
 ### 配置 TypeScript
 
 Intlayer 使用模块扩充来利用 TypeScript 的优势，并使您的代码库更强大。
@@ -1193,25 +1356,21 @@ Intlayer 使用模块扩充来利用 TypeScript 的优势，并使您的代码
 实际差异在于最终发送到浏览器的内容。基于命名空间的库会将整个 JSON 目录发送到页面，而 Intlayer 仅发送所渲染组件实际使用的内容，从而将 bundle 和页面体积减少高达 50%。请参阅 [为什么选择 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/interest_of_intlayer.md) 和 [Next.js i18n 性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/nextjs.md)。
 
 </Question>
-
 <Question title="i18n 会给我的 Next.js bundle 体积增加多少？">
 
 远少于基于命名空间的方案，因为页面永远不会下载它不渲染的语言目录。Server Components 在服务端直接解析其内容，构建时编译器将 `useIntlayer` 调用替换为组件使用的确切字典条目，因此未使用的键和未使用的语言都会被自动丢弃，并且 [动态字典](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md) 会按语言环境拆分剩余内容。与常规替代方案相比，Intlayer 可将 bundle 和页面体积减少高达 50%。请参阅 [Bundle 体积优化](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/bundle_optimization.md) 和 [性能基准](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/benchmark/nextjs.md)。
 
 </Question>
-
 <Question title="我可以从 next-intl、next-i18next 或 i18next 迁移而无需重写组件吗？">
 
 可以，有两条迁移路径。您可以使用 [next-intl 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_next-intl_to_intlayer.md) 或 [i18next 迁移指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/migration_from_i18next_to_intlayer.md) 逐步迁移内容。或者，您可以完全保留当前的 API：[兼容性适配器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compat/index.md) 公开与 `next-intl`、`react-i18next` 和 `react-intl` 完全相同的 API，但底层由 Intlayer 字典驱动，因此只需更改导入语句，组件代码完全无需修改。
 
 </Question>
-
 <Question title="我可以保留现有的 JSON 翻译文件吗？">
 
 可以。[JSON 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-json.md) 将您的 `/messages/{locale}/{namespace}.json` 文件作为单一真实来源（source of truth），并双向生成 Intlayer 字典。[PO 同步插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/plugins/sync-po.md) 对 gettext 目录执行相同的操作，而 [按语言环境组织的文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/per_locale_file.md) 允许您按语言拆分内容，而不是将所有语言打包到一个文件中。
 
 </Question>
-
 <Question title="我必须逐个键迁移我的内容吗？">
 
 不需要。运行 `npx intlayer extract`，Intlayer 会读取您的组件，提取面向用户的字符串，并在每个组件旁边生成 `.content` 文件，这样您只需审查 diff，而无需手动逐一复制字符串到语言目录中。本指南的第 14 步详细介绍了此过程。
@@ -1221,7 +1380,6 @@ Intlayer 使用模块扩充来利用 TypeScript 的优势，并使您的代码
 开启编译器前有两个限制值得了解：它通过静态分析工作，因此仅在运行时存在的字符串（如 API 错误代码或 CMS 字段）无法被捕获；此外它需要区分用户文本和应用程序逻辑（如 `className="active"` 或状态代码），在大型代码库中需要少量注解。而 [extract 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 则通过让您参与审查避免了这两个问题。
 
 </Question>
-
 <Question title="有哪些可用的编辑器和 AI 代理工具？">
 
 共有 5 个工具，均为可选：
@@ -1233,19 +1391,16 @@ Intlayer 使用模块扩充来利用 TypeScript 的优势，并使您的代码
 - **[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md)**：`no-raw-text` 规则标记硬编码字符串，并提供针对静态字典键和未使用内容的额外规则。
 
 </Question>
-
 <Question title="Intlayer 是否支持 Next.js App Router 和 React Server Components？">
 
 是的。`next-intlayer` 专为 App Router 构建：内容直接在 Server Components 内部的服务端解析，因此服务端渲染的文本不会向客户端发送任何字典。Client Components 则通过 Provider 使用相同的 `useIntlayer` Hook。Intlayer 不会阻碍静态渲染，并且与 Turbopack 完全兼容。
 
 </Question>
-
 <Question title="Intlayer 支持哪些 Next.js 版本？">
 
 Intlayer 支持 Next.js 12、13、14、15 和 16。本指南涵盖 Next.js 16。对于较旧的设置，请参阅 [Next.js 15 指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_15.md)、[Next.js 14 指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_14.md) 或 [Pages Router 指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_page_router.md)。
 
 </Question>
-
 <Question title="我必须在 URL 中加入语言环境（例如 /fr/about）吗？">
 
 不需要。URL 方案是配置选项而非限制。`routing.mode` 支持：
@@ -1255,40 +1410,34 @@ Intlayer 支持 Next.js 12、13、14、15 和 16。本指南涵盖 Next.js 16。
 - `"no-prefix"`：路径中无语言环境，从 Cookie、Header 或域名解析。
 - `"search-params"`：`/about?locale=fr`。
 
-您还可以通过 `routing.domains` 将每个语言环境映射到其独立的域名。请参阅 [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md) 和 [无语言路径指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_no_locale_path.md)。
+您还可以通过 `routing.domains` 将每个语言环境映射到其独立的域名。请参阅 [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md) 和 [步骤 2](#step-2-configure-your-project) 了解路由模式选项。
 
 </Question>
-
 <Question title="如何添加 hreflang 标签和本地化 SEO 元数据？">
 
 结合使用 Next.js 的 `generateMetadata` 函数与 Intlayer 的 `getMultilingualUrls`。它为每个声明的语言环境构建 `alternates.languages` 映射（包括 `x-default` 项），确保搜索引擎提供正确的语言版本。同一个辅助函数也可以本地化 `sitemap.ts` 和 `robots.ts`。本指南的第 8 步和第 9 步展示了完整代码。
 
 </Question>
-
 <Question title="如何使用 AI 自动翻译 Next.js 应用？">
 
 运行 `npx intlayer fill`。CLI 会检测内容文件中缺失的翻译，并使用您选择的 LLM、您自己的提供商和 API 密钥进行填充，因此直接向提供商付费，无需经过任何第三方。请参阅 [fill 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/fill.md) 和 [CI/CD 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/CI_CD.md)。
 
 </Question>
-
 <Question title="Intlayer 是否支持复数、性别、条件和富文本？">
 
 支持。内容声明支持 [复数形式](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/plurial.md)、[基于性别的内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/gender.md)、条件渲染、插值用的 [插入内容 (insertions)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/insertion.md)，以及用于法律页面或博客正文等富文本的 [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/markdown.md)。数字、日期和货币由 [格式化工具](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/formatters.md) 处理。
 
 </Question>
-
 <Question title="翻译人员与非开发人员如何编辑内容？">
 
 有两个选项，均为可选。[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md) 在您自己的基础设施上运行，允许任何人点击站点的文本直接就地编辑。[CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 将内容外部化，因此无需重新部署即可更新，并通过 [live sync](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/live.md) 在运行时反映更改。
 
 </Question>
-
 <Question title="如何在发布前捕获缺失的翻译？">
 
 在 CI 中运行 `npx intlayer test`。当声明的语言环境缺少内容时，它会使构建失败，确保未翻译的字符串永远不会进入生产环境。[VS Code 扩展](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md) 会在您键入时显示相同的错误，[ESLint 插件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/eslint.md) 及其 `no-raw-text` 规则会捕获硬编码字符串。请参阅 [测试您的内容](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/testing.md)。
 
 </Question>
-
 <Question title="Intlayer 是免费且开源的吗？">
 
 是的。Intlayer 基于 Apache 2.0 许可证开源，整个库、CLI、可视化编辑器和编译器均可免费使用，包括商业用途。托管版 CMS 是可选的付费服务，同时也完全支持 [自托管](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。