@intlayer/docs 8.12.4 → 9.0.0-canary.10

package/docs/zh/intlayer_with_nextjs_compiler.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-01-10
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Next.js i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Next.js 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -29,6 +29,7 @@ history:
   - version: 8.1.6
     date: 2026-02-23
     changes: "初始版本"
+author: aymericzip
 ---
 
 # 如何将现有的 Next.js 应用程序多语言化 (i18n) (i18n 指南 2026)
@@ -83,32 +84,50 @@ history:
 
 <Steps>
 
+<Steps>
+
 <Step number={1} title="安装依赖项">
 
 使用您偏好的包管理器安装必要的包：
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 该命令将检测您的环境并安装所需的软件包。例如：
+
 ```bash packageManager="npm"
 npm install intlayer next-intlayer
 npm install @intlayer/babel --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer next-intlayer
 pnpm add @intlayer/babel --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer next-intlayer
 yarn add @intlayer/babel --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer next-intlayer
 bun add @intlayer/babel --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -198,7 +217,30 @@ export default withIntlayer(nextConfig);
 > Next.js 插件 `withIntlayer()` 用于将 Intlayer 与 Next.js 集成。它确保字典文件的构建，并在开发模式下监视它们。它在 [Webpack](https://webpack.js.org/) 或 [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack) 环境中定义 Intlayer 环境变量。此外，它还提供别名以优化性能，并保留与服务器组件的兼容性。
 > </Step>
 
-<Step number={4} title="页面中的语言环境检测">
+<Step number={4} title="配置 Babel">
+
+Intlayer 编译器需要 Babel 来提取和优化您的内容。更新您的 `babel.config.js`（或 `babel.config.json`）以包含 Intlayer 插件：
+
+```typescript fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+</Step>
+
+<Step number={5} title="页面中的语言环境检测">
 
 清空 `RootLayout` 的内容，并将其替换为以下示例：
 
@@ -243,7 +285,7 @@ export default RootLayout;
 
 </Step>
 
-<Step number={5} title="声明您的内容（自动）">
+<Step number={6} title="声明您的内容（自动）">
 
 启用编译器后，您**不再需要**手动声明内容字典（例如 `.content.ts` 文件）。
 
@@ -340,6 +382,46 @@ export default async function Page() {
   > Layout and page cannot share a common server context because the server context system is based on a per-request data store (via [React's cache](https://react.dev/reference/react/cache) mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.
   > </Step>
 
+<Step number={7} title="填写缺失的翻译" isOptional={true}>
+
+Intlayer 提供了一个 CLI 工具来帮助您填写缺失的翻译。您可以使用 `intlayer` 命令来测试并从您的代码中填写缺失的翻译。
+
+```bash packageManager="npm"
+npx intlayer test         # 测试是否有缺失的翻译
+```
+
+```bash packageManager="yarn"
+yarn intlayer test         # 测试是否有缺失的翻译
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer test         # 测试是否有缺失的翻译
+```
+
+```bash packageManager="bun"
+bun x intlayer test         # 测试是否有缺失的翻译
+```
+
+```bash packageManager="npm"
+npx intlayer fill         # 填写缺失的翻译
+```
+
+```bash packageManager="yarn"
+yarn intlayer fill         # 填写缺失的翻译
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer fill         # 填写缺失的翻译
+```
+
+```bash packageManager="bun"
+bun x intlayer fill         # 填写缺失的翻译
+```
+
+> 有关更多详细信息，请参阅 [CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/ci.md)
+
+</Step>
+
 <Step number={8} title="本地化路由代理中间件" isOptional={true}>
 
 如果您希望自动将用户重定向到其偏好的语言环境，请建立代理解析中间件：
@@ -356,7 +438,89 @@ export const config = {
 > `intlayerProxy` 用于检测用户的首选语言环境，并根据 [配置文件设置](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md) 将其重定向到适当的 URL。此外，它还支持将用户的首选语言环境保存在 cookie 中。
 > </Step>
 
-<Step number={1} title="提取组件内容" isOptional={true}>
+<Step number={9} title="更改内容语言环境" isOptional={true}>
+
+在 Next.js 中更改内容语言环境的最推荐方法是使用 `Link` 组件将用户重定向到包含相应语言环境的路由。这将利用 Next.js 的预取功能，并避免页面强制刷新。
+
+```tsx fileName="src/components/localeSwitcher/LocaleSwitcher.tsx"
+"use client";
+
+import type { FC } from "react";
+import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+export const LocaleSwitcher: FC = () => {
+  const { locale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <button
+            key={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={() => setLocale(localeItem)}
+          >
+            <span>
+              {/* 语言环境 - 例如：ZH */}
+              {localeItem}
+            </span>
+            <span>
+              {/* 语言环境自身的名称 - 例如：中文 */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* 当前语言环境下的名称 - 例如：Francés（当当前语言环境为 Locales.SPANISH 时） */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* 英语下的名称 - 例如：Chinese */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+> 另一种方法是使用 `useLocale` 钩子提供的 `setLocale` 函数。该函数不支持页面预取。有关更多详细信息，请查看 [`useLocale` 钩子文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useLocale.md)。
+
+</Step>
+
+<Step number={10} title="优化包体积" isOptional={true}>
+
+使用 `next-intlayer` 时，字典默认会包含在每个页面的包中。为了优化包体积，Intlayer 提供了一个可选的 SWC 插件，它利用宏智能地优化 `useIntlayer` 调用。这确保了字典仅包含在实际使用它们的页面的包中。
+
+要启用此优化，请安装 `@intlayer/swc` 包。安装后，`next-intlayer` 会自动检测并使用该插件：
+
+```bash packageManager="npm"
+npm install @intlayer/swc --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/swc --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/swc --save-dev
+```
+
+```bash packageManager="bun"
+bun add @intlayer/swc --dev
+```
+
+> 注意：此优化仅适用于 Next.js 13 及以上版本。
+
+> 注意：由于 Next.js SWC 插件仍处于试验阶段，该包默认未安装。未来可能会有所改变。
+
+> 注意：如果您设置了 `importMode: 'dynamic'` 或 `importMode: 'fetch'`（在字典配置中），它将依赖于 Suspense，因此您需要将 `useIntlayer` 调用包裹在 `Suspense` 边界内。这意味着您无法直接在页面/布局组件的顶层使用 `useIntlayer`。
+
+</Step>
+
+<Step number={11} title="提取组件内容" isOptional={true}>
 
 如果您有现有的代码库，转换数千个文件可能会非常耗时。
 
@@ -419,6 +583,8 @@ 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
 ```
@@ -472,142 +638,7 @@ bun run build # Or bun run dev
 
 </Steps>
 
-### 配置 Babel
-
-Intlayer 编译器需要 Babel 来提取和优化您的内容。更新您的 `babel.config.js`（或 `babel.config.json`）以包含 Intlayer 插件：
-
-```typescript fileName="babel.config.js"
-const {
-  intlayerExtractBabelPlugin,
-  intlayerOptimizeBabelPlugin,
-  getExtractPluginOptions,
-  getOptimizePluginOptions,
-} = require("@intlayer/babel");
-
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
-    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
-  ],
-};
-```
-
-### (可选) 第 7 步：填写缺失的翻译
-
-Intlayer 提供了一个 CLI 工具来帮助您填写缺失的翻译。您可以使用 `intlayer` 命令来测试并从您的代码中填写缺失的翻译。
-
-```bash packageManager="npm"
-npx intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="yarn"
-yarn intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="bun"
-bun x intlayer test         # 测试是否有缺失的翻译
-```
-
-```bash packageManager="npm"
-npx intlayer fill         # 填写缺失的翻译
-```
-
-```bash packageManager="yarn"
-yarn intlayer fill         # 填写缺失的翻译
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer fill         # 填写缺失的翻译
-```
-
-```bash packageManager="bun"
-bun x intlayer fill         # 填写缺失的翻译
-```
-
-> 有关更多详细信息，请参阅 [CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/ci.md)
-
-### (可选) 第 9 步：更改内容语言环境
-
-在 Next.js 中更改内容语言环境的最推荐方法是使用 `Link` 组件将用户重定向到包含相应语言环境的路由。这将利用 Next.js 的预取功能，并避免页面强制刷新。
-
-```tsx fileName="src/components/localeSwitcher/LocaleSwitcher.tsx"
-"use client";
-
-import type { FC } from "react";
-import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
-import { useLocale } from "next-intlayer";
-
-export const LocaleSwitcher: FC = () => {
-  const { locale, availableLocales, setLocale } = useLocale();
-
-  return (
-    <div>
-      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
-      <div id="localePopover" popover="auto">
-        {availableLocales.map((localeItem) => (
-          <button
-            key={localeItem}
-            aria-current={locale === localeItem ? "page" : undefined}
-            onClick={() => setLocale(localeItem)}
-          >
-            <span>
-              {/* 语言环境 - 例如：ZH */}
-              {localeItem}
-            </span>
-            <span>
-              {/* 语言环境自身的名称 - 例如：中文 */}
-              {getLocaleName(localeItem, locale)}
-            </span>
-            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
-              {/* 当前语言环境下的名称 - 例如：Francés（当当前语言环境为 Locales.SPANISH 时） */}
-              {getLocaleName(localeItem)}
-            </span>
-            <span dir="ltr" lang={Locales.ENGLISH}>
-              {/* 英语下的名称 - 例如：Chinese */}
-              {getLocaleName(localeItem, Locales.ENGLISH)}
-            </span>
-          </button>
-        ))}
-      </div>
-    </div>
-  );
-};
-```
-
-> 另一种方法是使用 `useLocale` 钩子提供的 `setLocale` 函数。该函数不支持页面预取。有关更多详细信息，请查看 [`useLocale` 钩子文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useLocale.md)。
-
-### (可选) 第 10 步：优化包体积
-
-使用 `next-intlayer` 时，字典默认会包含在每个页面的包中。为了优化包体积，Intlayer 提供了一个可选的 SWC 插件，它利用宏智能地优化 `useIntlayer` 调用。这确保了字典仅包含在实际使用它们的页面的包中。
-
-要启用此优化，请安装 `@intlayer/swc` 包。安装后，`next-intlayer` 会自动检测并使用该插件：
-
-```bash packageManager="npm"
-npm install @intlayer/swc --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add @intlayer/swc --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add @intlayer/swc --save-dev
-```
-
-```bash packageManager="bun"
-bun add @intlayer/swc --dev
-```
-
-> 注意：此优化仅适用于 Next.js 13 及以上版本。
-
-> 注意：由于 Next.js SWC 插件仍处于试验阶段，该包默认未安装。未来可能会有所改变。
-
-> 注意：如果您设置了 `importMode: 'dynamic'` 或 `importMode: 'fetch'`（在字典配置中），它将依赖于 Suspense，因此您需要将 `useIntlayer` 调用包裹在 `Suspense` 边界内。这意味着您无法直接在页面/布局组件的顶层使用 `useIntlayer`。
+</Steps>
 
 ### TypeScript 配置
 

package/docs/zh/intlayer_with_nextjs_no_locale_path.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-01-10
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Next.js 16 i18n - 翻译你的应用的完整指南"
 description: "告别 i18next。2026 年构建多语言 (i18n) Next.js 16 应用的完整指南。使用 AI 代理翻译并优化包体积、SEO 和性能。"
 keywords:
@@ -24,6 +24,7 @@ history:
   - version: 8.0.0
     date: 2026-01-10
     changes: "初始发布"
+author: aymericzip
 ---
 
 # 使用 Intlayer 翻译你的 Next.js 16 网站（页面路径中不包含 [locale]） | 国际化 (i18n)
@@ -97,24 +98,40 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 使用 npm 安装所需的包：
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 该命令将检测您的环境并安装所需的软件包。例如：
+
 ```bash packageManager="npm"
 npm install intlayer next-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer next-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer next-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer next-intlayer
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -127,7 +144,7 @@ bun x intlayer init
 
 <Steps>
 
-<Step number={2} title="配置您的项目">
+<Step number={1} title="配置您的项目">
 
 下面是我们将创建的最终结构：
 
@@ -181,9 +198,10 @@ export default config;
 ```
 
 > 通过此配置文件，您可以设置本地化 URL、代理重定向、cookie 名称、内容声明的位置和扩展名、在控制台禁用 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-> </Step>
 
-<Step number={5} title="声明您的内容">
+</Step>
+
+<Step number={2} title="声明您的内容">
 
 创建并管理您的内容声明以存储翻译：
 
@@ -303,7 +321,7 @@ export default pageContent;
 
 </Step>
 
-<Step number={6} title="在代码中使用内容">
+<Step number={3} title="在代码中使用内容">
 
 在应用程序中随处访问你的内容字典：
 
@@ -407,7 +425,7 @@ export const ServerComponentExample: FC = () => {
 
 </Step>
 
-<Step number={7} title="配置 Proxy 以进行 locale 检测">
+<Step number={4} title="配置 Proxy 以进行 locale 检测">
 
 设置 Proxy 以检测用户的首选 locale：
 
@@ -433,7 +451,7 @@ export const proxy = multipleProxies([intlayerProxy, customProxy]);
 
 </Step>
 
-<Step number={8} title="更改您内容的语言">
+<Step number={5} title="更改您内容的语言">
 
 要在 Next.js 中更改内容的语言，推荐的方法是使用 `Link` 组件将用户重定向到相应的本地化页面。`Link` 组件支持页面预取，这有助于避免整页重新加载。
 
@@ -494,7 +512,9 @@ export const LocaleSwitcher: FC = () => {
 > - [`dir` attribute`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
 > - [`aria-current` attribute`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)
 
-###（可选）步骤 9：在 Server Actions 中获取当前 locale
+</Step>
+
+<Step number={6} title="在 Server Actions 中获取当前 locale" isOptional={true}>
 
 如果你需要在 Server Action 中使用活动 locale（例如，用于本地化电子邮件或运行与 locale 相关的逻辑），请从 `next-intlayer/server` 调用 `getLocale`：
 
@@ -521,7 +541,7 @@ export const myServerAction = async () => {
 
 </Step>
 
-<Step number={10} title="优化你的 bundle 大小">
+<Step number={7} title="优化你的 bundle 大小">
 
 在使用 `next-intlayer` 时，字典默认会被包含到每个页面的 bundle 中。为了优化 bundle 大小，Intlayer 提供了一个可选的 SWC 插件，它使用宏智能替换 `useIntlayer` 调用。这样只有实际使用这些字典的页面的 bundle 才会包含相应字典。
 
@@ -548,11 +568,10 @@ bun add @intlayer/swc --dev
 > 注意：该包默认不安装，因为 SWC 插件在 Next.js 中仍然是实验性的。将来可能会发生变化。
 
 > 注意：如果你将选项设置为 `importMode: 'dynamic'` 或 `importMode: 'fetch'`，它将依赖 Suspense，因此你必须在一个 `Suspense` 边界中包裹你的 `useIntlayer` 调用。这意味着你不能在页面 / 布局组件的顶层直接使用 `useIntlayer`。
-> </Step>
 
-</Steps>
+</Step>
 
-### 第 3 步：在 Next.js 配置中集成 Intlayer
+<Step number={8} title="第 3 步：在 Next.js 配置中集成 Intlayer">
 
 配置您的 Next.js 设置以使用 Intlayer：
 
@@ -595,7 +614,9 @@ export default withIntlayer(nextConfig);
 > withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));
 > ```
 
-### 第4步：定义动态 locale 路由
+</Step>
+
+<Step number={9} title="第4步：定义动态 locale 路由">
 
 从 `RootLayout` 中删除所有内容，并用下面的代码替换：
 
@@ -638,7 +659,9 @@ const RootLayout = async ({
 export default RootLayout;
 ```
 
-### 在 Turbopack 上监视字典更改
+</Step>
+
+<Step number={10} title="在 Turbopack 上监视字典更改">
 
 当使用 Turbopack 作为通过 `next dev` 命令运行的开发服务器时，字典更改默认不会被自动检测。
 
@@ -656,6 +679,10 @@ export default RootLayout;
 
 > 如果你使用的是 next-intlayer@<=6.x.x，你需要保留 `--turbopack` 标志以使 Next.js 16 应用程序能与 Turbopack 正常工作。我们建议使用 next-intlayer@>=7.x.x 来避免此限制。
 
+</Step>
+
+</Steps>
+
 ### 配置 TypeScript
 
 Intlayer 使用模块扩展（module augmentation）来利用 TypeScript 的优势并增强你的 codebase 的类型安全性。