@intlayer/docs 9.1.3 → 9.3.0

package/docs/zh/packages/vite-intlayer/exports.md

@@ -37,6 +37,26 @@ npm install vite-intlayer
 
 导入：
 
+```ts
+import { ... } from "vite-intlayer";
+```
+
+| 导出                       | 描述                                                                                                      | 相关文档                                                                                                                     |
+| -------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `intlayer`                 | 主要 Vite 插件。准备字典、配置别名、启动开发服务器监听器，以及（从 v9 开始）捆绑代理和编译器。            | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayer.md)                 |
+| `intlayerPlugin`           | (**已弃用**) `intlayer` 的别名。                                                                          | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayer.md)                 |
+| `intLayerPlugin`           | (**已弃用**) `intlayer` 的别名。                                                                          | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayer.md)                 |
+| `intlayerProxy`            | 本地化路由中间件插件（检测、重定向、重写）。从 v9 开始，它捆绑在 `intlayer()` 内部 — 仅在需要时单独注册。 | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerProxy.md)       |
+| `intlayerMiddleware`       | (**已弃用**) `intlayerProxy` 的别名。                                                                     | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerProxy.md)       |
+| `intLayerMiddlewarePlugin` | (**已弃用**) `intlayerProxy` 的别名。                                                                     | [intlayerProxy](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerProxy.md)       |
+| `intlayerCompiler`         | 从组件中提取内联内容声明并将其写入字典。从 v9 开始，它捆绑在 `intlayer()` 内部。                          | [intlayerCompiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerCompiler.md) |
+| `intlayerPrune`            | 从生产 bundle 中树摇未使用的字典字段。                                                                    | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerPrune.md)       |
+| `intlayerMinify`           | 压缩编译后的字典 JSON 文件，并可选地破坏字段名。                                                          | [intlayerMinify](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerMinify.md)     |
+
+### 插件
+
+导入：
+
 ```tsx
 import "vite-intlayer";
 ```
@@ -48,3 +68,12 @@ import "vite-intlayer";
 | `intlayerProxy`      | 开发时的中间件插件，用于处理语言检测和路由。               | -                                                                                                                      |
 | `intlayerMiddleware` | (**已弃用**) `intlayerProxy` 的别名。                      | -                                                                                                                      |
 | `intlayerPrune`      | 用于在构建期间对未使用的字典进行 tree-shake 和修剪的插件。 | [intlayerPrune](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerPrune.md) |
+
+### 类型
+
+| 导出                         | 描述                                                                                               |
+| ---------------------------- | -------------------------------------------------------------------------------------------------- |
+| `IntlayerPluginOptions`      | `intlayer()` 接受的选项。扩展 `GetConfigurationOptions`，添加 `compatCallers` 和 `proxy`。         |
+| `IntlayerProxyPluginOptions` | `intlayerProxy()` 和 `createIntlayerProxyHandler()` 接受的选项。包括 `ignore` 和 `configOptions`。 |
+| `IntlayerCompilerOptions`    | `intlayerCompiler()` 接受的选项。包括 `configOptions` 和 `compilerConfig`。                        |
+| `CompatCallerConfig`         | 从 `@intlayer/babel` 重新导出。描述用于字段使用分析的 compat-adapter 调用者模式。                  |

package/docs/zh/packages/vite-intlayer/intlayer.md

@@ -39,11 +39,126 @@ export default defineConfig({
 });
 ```
 
-## 描述
+## 选项
 
-该插件执行以下任务：
+```ts
+import type { IntlayerPluginOptions } from "vite-intlayer";
+```
+
+`IntlayerPluginOptions` 扩展了 `GetConfigurationOptions`（参见 `@intlayer/config`），并添加了以下额外字段：
+
+| 选项            | 类型                            | 默认值      | 描述                                                                                                |
+| --------------- | ------------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
+| `compatCallers` | `CompatCallerConfig[]`          | `[]`        | compat-adapter 包的额外调用者模式（例如 `@intlayer/react-i18next`）。在构建时传递给字段使用分析器。 |
+| `proxy`         | `{ ignore?: (req) => boolean }` | `undefined` | 转发到捆绑的区域设置路由代理的选项。使用 `ignore` 排除特定路径（例如 API 路由）不进行区域设置路由。 |
+
+所有其他选项（`override`、`configFile`、…）直接转发到 `getConfiguration()`。
+
+### 示例
+
+#### 忽略来自区域设置路由的 API 路由
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+#### 使用自定义配置文件路径
+
+```ts
+export default defineConfig({
+  plugins: [
+    intlayer({
+      configFile: "./config/intlayer.config.ts",
+    }),
+  ],
+});
+```
+
+#### 带有 compat-adapter 调用者
+
+```ts
+import { intlayer } from "vite-intlayer";
+import { reactI18nextCallerConfig } from "@intlayer/react-i18next/plugin";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      compatCallers: [reactI18nextCallerConfig],
+    }),
+  ],
+});
+```
+
+## 插件的作用
+
+### 1. 字典准备
+
+在构建开始前（以及开发中每小时一次），`intlayer` 调用 `prepareIntlayer` 来编译所有 `.content.ts` 文件到存储在 `.intlayer/` 中的优化 JSON 字典。
+
+### 2. Module aliases
+
+该插件添加了 Vite resolve aliases，使得 `import { myDict } from 'intlayer/dictionaries/my-dict'` 能够解析到磁盘上的已编译 JSON 文件。SSR 构建使用 `ssr.noExternal` 来确保所有 `@intlayer/*` packages 都与应用的 aliases 一起打包。
+
+### 3. Dev-server watcher
+
+在开发模式下，会启动一个 `chokidar` watcher。当 `.content.ts` 文件变化时，字典会被重新编译，Vite 的 HMR 会将更新传播到浏览器。
+
+### 4. 捆绑的语言环境路由代理 (v9+)
+
+自 Intlayer v9 起，`intlayerProxy` 中间件会自动在 `intlayer()` 内注册。它处理：
+
+- 从 URL 前缀、cookies 和 `Accept-Language` 头进行语言环境检测。
+- 当检测到的语言环境与当前 URL 不匹配时进行 301 重定向。
+- 内部 URL 重写，以便框架看到正确的 `[locale]` 路由参数。
+
+代理由 Intlayer 配置中的 `routing.enableProxy`（默认 `true`）控制。要完全禁用它：
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  routing: { enableProxy: false },
+});
+```
+
+要在不进行单独 `intlayerProxy()` 调用的情况下自定义代理行为，请将 `proxy` 选项传递给主插件：
+
+```ts
+intlayer({ proxy: { ignore: (req) => req.url?.startsWith("/api") } });
+```
+
+有关完整的路由行为参考，请参阅 [intlayerProxy 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerProxy.md)。
+
+### 5. Bundled compiler (v9+)
+
+当 `compiler.enabled` 为 `true` **且** `compiler.output` 在你的 Intlayer config 中设置时，`intlayer()` 会自动注册 `intlayerCompiler`。编译器提取直接写在组件文件中的内联内容声明，并在转换时将其写入字典。参见 [intlayerCompiler 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vite-intlayer/intlayerCompiler.md)。
+
+### 6. 构建优化
+
+在生产构建期间，插件会添加：
+
+- **intlayerOptimize** – Babel 转换，将 `useIntlayer('key')` 重写为 `useDictionary(hash)` 并注入直接的 JSON 导入。
+- **intlayerPrune** – 从字典 JSON 中删除未使用的内容字段。
+- **intlayerMinify** – 压缩字典 JSON，并可选地混淆字段名。
+
+这些在开发模式下处于非活动状态。
+
+## 已弃用的别名
 
-1. **准备字典**：在构建或开发过程开始时，将字典编译为优化后的文件。
-2. **监听模式**：在开发模式下，它会监视字典文件的更改并自动重新编译。
-3. **别名**：为在应用中访问字典提供别名。
-4. **Tree-shaking**：它通过 `intlayerPrune` 插件支持对未使用的翻译进行 tree-shaking。
+| 已弃用的导出     | 替换项     |
+| ---------------- | ---------- |
+| `intlayerPlugin` | `intlayer` |
+| `intLayerPlugin` | `intlayer` |

package/docs/zh/packages/vite-intlayer/intlayerPrune.md

@@ -28,18 +28,91 @@ author: aymericzip
 
 `intlayerPrune` Vite 插件用于对应用包中未使用的字典进行 tree-shaking 和裁剪。这样可以通过仅包含必要的多语言内容来减小最终包的体积。
 
-## 用法
+## 使用
+
+### 作为 `intlayer()` 的一部分（推荐）
+
+通过您的 Intlayer 配置启用剪枝，主插件会处理一切：
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // 启用剪枝和最小化
+  },
+});
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+### 独立使用
+
+如果您是手动组合插件堆栈，`intlayerPrune` 和 `intlayerMinify` 共享一个 `PruneContext` 对象，该对象必须创建一次并传递给两者：
 
 ```ts
-// vite.config.ts（Vite 配置）
+// vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // 可选，从同一上下文读取
+  ],
 });
 ```
 
-## 描述
+## 它的工作原理
+
+### 1. 使用情况分析 (buildStart)
+
+在 `buildStart` 期间，`intlayerOptimize` 插件（也是 `intlayer()` 的一部分）扫描 `build.filesList` 中列出的每个组件源文件。对于每个 `useIntlayer('key')` 或 `getIntlayer('key')` 调用，它会准确记录访问了哪些字段，例如：
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// 记录: myDict → { title, description }
+```
+
+这在任何 `transform` 调用运行之前建立了 `pruneContext.fieldUsageMap`。
+
+### 2. JSON 修剪 (transform, enforce: 'pre')
+
+当 Vite 处理编译的字典 JSON 文件时，`intlayerPrune` 在 Vite 的内置 JSON → ESM 转换之前拦截它。它从 `pruneContext` 读取字段使用情况映射，并删除任何不在记录的使用集中的内容字段。
+
+支持两种内容形状：
+
+- **静态字典** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`。字段在 `translation` 内按语言环境修剪。
+- **动态（按语言环境）字典** — 扁平化 `{ fieldA: ..., fieldB: ... }`。字段在顶级进行修剪。
+
+### 3. Edge cases
+
+如果字典的内容结构无法识别（例如，不寻常的嵌套形状），它会被添加到 `pruneContext.dictionariesWithEdgeCases` 中并**保持不变**。会记录一条警告。`intlayerMinify` 也会跳过这些字典。
+
+### 4. Field-rename map
+
+当剪枝成功时，`intlayerPrune` 也会写入 `pruneContext.dictionaryKeyToFieldRenameMap` — 一个从原始字段名到简短别名的映射。`intlayerMinify` 读取此映射以在输出 JSON 中重命名字段，而 `intlayerOptimize` 的 Babel 重命名传递相应地更新源文件中的属性访问。
+
+## 激活条件
+
+`intlayerPrune` **仅当**以下所有条件都为真时才会激活：
+
+1. Vite 命令是 `build`。
+2. `build.optimize` 是 `true`（或 `undefined`，在构建时默认为 `true`）。
+3. 在您的 Intlayer 配置中 `build.purge` 是 `true`。
 
-该插件会分析你的源代码以识别哪些字典键实际上被使用。然后它会从打包后的字典文件中移除任何未使用的内容。对于拥有大量字典但在特定页面或组件中仅使用其中一部分的大型项目，这尤其有用。
+当 `editor.enabled` 是 `true` 时，它会自动**禁用**，因为编辑器需要完整的字典内容。

package/docs/zh/releases/v9.md

@@ -358,6 +358,18 @@ await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
 
 ---
 
+## 自托管
+
+Intlayer v9 提供一流的支持，使您可以通过单个命令运行自己的 Intlayer 实例。无需 Intlayer Cloud 账户。
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+安装程序下载 `docker-compose.yml` 和 `.env`，自动生成所需的密钥，并运行 `docker compose up -d`。一切内容 — dashboard、API、数据库、对象存储和事务性电子邮件 — 都在容器中本地运行。
+
+---
+
 ## Migration notes from v8
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:

package/docs/zh/self_hosting.md

@@ -64,6 +64,32 @@ Chromium（用于 Puppeteer 屏幕截图生成）捆绑在后端镜像中——
 
 ## 快速开始
 
+Pull 并运行已发布的镜像，提供您的 MongoDB Atlas 凭证和密钥：
+
+```sh
+docker run -d --name intlayer \
+  -p 3000:3000 \
+  -p 3100:3100 \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v intlayer-data:/data \
+  -e DB_ID="<atlas-user>" \
+  -e DB_MDP="<atlas-password>" \
+  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
+  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \
+  -e RESEND_API_KEY="<your-resend-key>" \
+  aymericzip/intlayer-selfhost
+```
+
+然后打开 **http://localhost:3000**。
+
+> dashboard 在 `localhost` 上提供。请参阅 [限制](#limitations) — 已发布的镜像不支持自定义域名。
+
+---
+
+## 快速开始
+
 ```sh
 curl -fsSL https://intlayer.org/install.sh | sh
 ```
@@ -99,7 +125,16 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ## 环境变量
 
-安装程序会生成一个即用型 `.env` 文件。下表描述了每个变量。
+### 必需
+
+| Variable               | Example                      | Description                                                                                                          |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas 用户                                                                                                   |
+| `DB_MDP`               | _(your password)_            | MongoDB Atlas 密码                                                                                                   |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas 集群主机（在 `mongodb+srv://` URI 中使用）                                                             |
+| `BETTER_AUTH_SECRET`   | _(generated)_                | 用于会话签名的 32 字节密钥                                                                                           |
+| `S3_SECRET_ACCESS_KEY` | _(generated)_                | 捆绑 MinIO 的密钥                                                                                                    |
+| `RESEND_API_KEY`       | _(your key)_                 | 通过 Resend 发送事务性邮件。除非你配置全局 SMTP 邮件器（见[全局邮件器](#global-mailer)），否则首次运行设置时为必需项 |
 
 ### 必需（自动生成或提示）
 
@@ -141,6 +176,26 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ---
 
+### 全局邮件服务
+
+默认情况下，所有事务性电子邮件都通过使用 `RESEND_API_KEY` 的 Resend 发送。自托管部署可以改为通过配置了环境变量的全局邮件服务路由**所有**电子邮件 — 包括非组织电子邮件，例如密码重置和魔法链接。
+
+设置 `MAIL_PROVIDER` 以激活它。如果未设置，将使用默认的 Resend 邮件服务。
+
+| 变量                 | 示例                           | 描述                                         |
+| -------------------- | ------------------------------ | -------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | 全局传输：`smtp` 或 `resend`。留空使用默认值 |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | 发件人标题。接受裸地址或 `Name <email>` 格式 |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP 主机（当 `MAIL_PROVIDER=smtp` 时必需）  |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP 端口（默认为 `587`）                    |
+| `MAIL_SMTP_SECURE`   | `false`                        | 隐式 TLS。对于端口 `465` 设置为 `true`       |
+| `MAIL_SMTP_USER`     | _（你的用户名）_               | SMTP 用户名（可选；无身份验证中继可省略）    |
+| `MAIL_SMTP_PASSWORD` | _（你的密码）_                 | SMTP 密码                                    |
+
+> 优先级：组织自己的邮件服务（从**组织**仪表板配置）优先于全局邮件服务，全局邮件服务优先于默认的 Resend 密钥。
+
+---
+
 ## 连接您的 Intlayer 项目
 
 堆栈运行后，将您的项目指向自托管的后端和仪表盘，而不是 `intlayer.org`。
@@ -259,47 +314,11 @@ docker run --rm \
 
 ---
 
-## 使用反向代理 (Nginx / Caddy)
-
-对于生产部署，请在应用和后端容器前放置一个反向代理，而不是直接暴露它们。
-
-### Nginx 示例
-
-```nginx
-server {
-    listen 80;
-    server_name cms.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
+## 限制条件
 
-server {
-    listen 80;
-    server_name api.example.com;
-
-    location / {
-        proxy_pass http://localhost:3100;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-}
-```
-
-更新以下 `.env` 变量以匹配您的公共域名：
-
-```sh
-BACKEND_URL=https://api.example.com
-APP_URL=https://cms.example.com
-DOMAIN=example.com
-VITE_BACKEND_URL=https://api.example.com
-VITE_DOMAIN=example.com
-```
-
-> `VITE_*` 变量在构建时被嵌入到仪表盘镜像中。如果在镜像构建后更改它们，您需要重建 `app` 镜像 (`docker compose build app`) 或使用运行时配置注入。
+- **MongoDB 必须是外部的 (Atlas)。** 后端仅通过 `mongodb+srv://` 连接（由 `DB_ID` / `DB_MDP` / `DB_CLUSTER` 构建），因此不能使用普通的 `mongodb://host:27017` — 包括容器自己的捆绑 `mongod`。请提供一个 MongoDB Atlas 集群。
+- **不支持自定义域名。** 所有面向浏览器的 `VITE_*` URL 都在构建时内联到应用中，发布的镜像带有 `localhost` 值。必须在 `http://localhost:3000` 上访问仪表板；在公共域上提供服务需要使用目标 URL 重新构建镜像，这在开箱即用时不受支持。
+- **Email 需要工作的邮件程序。** 首次运行设置强制执行电子邮件验证，因此必须配置 `RESEND_API_KEY` 或 [全局 SMTP 邮件程序](#global-mailer)（`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`）。第一个管理员登录后，每个组织也可以从仪表板配置自己的 SMTP 或 Resend 邮件程序。
 
 ---
 
@@ -315,15 +334,6 @@ docker compose logs mongo
 docker compose logs redis
 ```
 
-### 仪表盘无法连接到 API
-
-验证 `VITE_BACKEND_URL` 是否与后端可以从**浏览器**（而非 Docker 网络）访问的 URL 匹配。如果您更改了后端端口或添加了反向代理，请重建仪表盘镜像：
-
-```sh
-docker compose build app
-docker compose up -d app
-```
-
 ### 电子邮件未发送
 
 默认情况下，所有出站电子邮件都会被 Mailpit 捕获。打开 `http://localhost:8025` 查看已发送的消息。要发送真实电子邮件，请在 `.env` 中设置 `MAIL_PROVIDER=resend` 和 `RESEND_API_KEY=<your-key>`，然后重启后端：

package/docs/zh-TW/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: 最佳化 i18n 打包體積與效能
 description: 透過最佳化國際化（i18n）內容來縮減應用程式包的大小。了解如何利用 Intlayer 實現字典的 tree shaking 和延遲載入（lazy loading）。
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` 與 `minify` 現在可透過 `@intlayer/swc` 在 Next.js 上運作 — 不需要 `babel.config.js`"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "在參考表中依所需的流水線順序列出 Babel 外掛（extract → purge → minify → optimize）"
   - version: 8.12.0
     date: 2026-06-07
     changes: "為 Babel/Webpack 引入了 `intlayerPurgeBabelPlugin` 和 `intlayerMinifyBabelPlugin`，明確了外掛程式管線"
@@ -191,12 +197,14 @@ Intlayer 的建置最佳化被劃分為若干個職責單一的外掛程式。
 
 這些被直接運用在基於 Webpack 設定的 `babel.config.js` 當中（比如使用了 Babel 的 Next.js、CRA，或是自訂的 Webpack 等）。
 
+下表依所需的流水線順序列出它們（與它們必須在 `babel.config.js` 中出現的順序相同）：
+
 | 外掛程式                      | 功能說明                                                                                               |
 | :---------------------------- | :----------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | 掃描 `.content.ts` 檔案並把編譯好的字典寫入 `.intlayer/`                                               |
-| `intlayerOptimizeBabelPlugin` | 將 `useIntlayer('key')` 重寫為 `useDictionary(hash)` 並注入匹配對應字典的 `import` 語句                |
 | `intlayerPurgeBabelPlugin`    | 掃描所有原始碼檔案，從已編譯的 `.intlayer/**/*.json` 字典檔案中刪除**未被使用的內容欄位**              |
 | `intlayerMinifyBabelPlugin`   | **重新命名內容欄位的鍵（keys）** 為簡短的字母別名（例如 `title` 變成 `a`），作用範圍包括 JSON 與原始碼 |
+| `intlayerOptimizeBabelPlugin` | 將 `useIntlayer('key')` 重寫為 `useDictionary(hash)` 並注入匹配對應字典的 `import` 語句                |
 
 > **外掛程式的執行順序很重要。** 在您的 `babel.config.js` 裡，purge 和 minify 的外掛程式必須放置在 optimize 外掛程式**之前**。最佳化步驟（optimize）會把 `useIntlayer('key')` 替換為模糊的 `useDictionary(hash)`，此舉抹除了能夠讓 purge 和 minify 識別哪些欄位被使用過的字典 key 資訊。
 
@@ -205,9 +213,9 @@ Intlayer 的建置最佳化被劃分為若干個職責單一的外掛程式。
 | 選項助手                     | 配套外掛程式                  |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Vite 外掛程式 (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Vite 使用者**不需要直接對它們進行設定**。當您在 `vite.config.
 | Dictionary minify  | 等同於 `intlayerMinifyBabelPlugin` 的 JSON 寫入步驟                                     |
 | Babel transform    | 等同於 `intlayerMinifyBabelPlugin` 的程式碼重新命名步驟 + `intlayerOptimizeBabelPlugin` |
 
+### SWC 外掛（`@intlayer/swc`）
+
+Next.js 使用者同樣**從不直接設定這些**。自 **v9.2.1** 起，`next.config.ts` 中的 `withIntlayer()` 僅憑 `build.purge` 與 `build.minify` 兩個旗標就會執行完整流水線 —— 清除、壓縮與匯入重寫。
+
+工作被分成兩部分，因為 SWC Wasm 外掛一次只轉換一個檔案，且無法存取檔案系統：
+
+| 階段                                 | 執行位置                       | 作用                                                           |
+| :----------------------------------- | :----------------------------- | :------------------------------------------------------------- |
+| 使用分析 + JSON 清除/壓縮            | Node，位於 `withIntlayer()` 內 | 讀取每個元件原始檔，重寫 `.intlayer/**/*.json`，產生重新命名表 |
+| 原始碼重寫（`content.title` → `.a`） | `@intlayer/swc`（Wasm）        | 將重新命名表套用到你程式碼中對應的屬性存取                     |
+| 匯入重寫（`useIntlayer` → dict）     | `@intlayer/swc`（Wasm）        | 與 `intlayerOptimizeBabelPlugin` 相同                          |
+
+判斷_哪些_欄位未被使用以及每個欄位取得_什麼_別名，需要跨檔案狀態與檔案 I/O，因此這一半在 Node 中執行；SWC 外掛只接收產生的表。
+
 ## 各平台設定指南
 
 <Tabs>
@@ -227,10 +249,12 @@ Vite 使用者**不需要直接對它們進行設定**。當您在 `vite.config.
 
 ### Next.js
 
-Next.js 需要依靠 `@intlayer/swc` 外掛程式來進行最佳化步驟（匯入重寫），因為 Next.js 採用 SWC 作為編譯器。
+Next.js 需要 `@intlayer/swc` 外掛，因為 Next.js 使用 SWC 進行建置。自 **v9.2.1** 起，這一個套件即可涵蓋整條流水線 —— 最佳化（匯入重寫）、清除與壓縮。
 
 > 該外掛程式並未預設安裝，因為 SWC 外掛程式在 Next.js 當中目前仍處於實驗階段。未來這部分有可能會發生改變。
 
+> **Next.js 16.1.0 是最低版本。** 它是首個基於 SWC 向前相容 Wasm 外掛 ABI 建置的版本；更早的版本會拒絕該外掛。`withIntlayer` 會讀取你專案的 Next.js 版本，低於 16.1.0 時乾脆不註冊該外掛 —— 這些建置仍會成功，只是在沒有打包最佳化的情況下執行。
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 安裝完畢後，Intlayer 將會自動偵測並使用該外掛程式。
 
-至於**清除（purge）和最小化（minify）**步驟（即欄位移除和欄位重新命名），請連同 `@intlayer/babel` 一併安裝並加入 Babel 外掛程式。由於 Next.js 依靠 SWC 處理程式碼轉化，但仍會評估 `babel.config.js` 以決定外掛程式設定，因此上述 Babel 外掛程式能夠在進入 SWC 前作為預處理步驟得以執行。
+**清除與壓縮**階段（欄位移除與欄位重新命名）不需要額外套件，也不需要 `babel.config.js`。用 `withIntlayer` 包住你的設定，並在 `intlayer.config.ts` 中開啟相應旗標：
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* 你的設定 */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: 移除 .intlayer/**/*.json 裡未被使用的內容欄位
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: 對 JSON 以及原始碼裡的內容欄位的鍵（keys）進行重新命名
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // 注意: 在這裡不需要使用 intlayerOptimizeBabelPlugin，因為
-    // @intlayer/swc 已經處理了 useIntlayer → useDictionary 的重寫過程。
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // 從打包的 JSON 中移除未使用的內容欄位
+    minify: true, // 將內容欄位鍵重新命名為簡短別名
+  },
 };
+
+export default config;
 ```
 
+在 `next build` 期間，`withIntlayer` 會分析你的原始碼、重寫已編譯的字典，並將產生的欄位重新命名表交給 `@intlayer/swc`，由它更新你程式碼中對應的屬性存取。
+
+> 請使用非同步的 `withIntlayer`，而不是 `withIntlayerSync`。同步版本不會執行分析流水線，因此清除與壓縮對它沒有效果。
+
+> 清除與壓縮僅在 `next build` 時執行 —— 最佳化流水線在 `next dev` 期間是關閉的。
+
+> 當設定了相容轉接器呼叫方時它們也會被停用（`swcExtraCallers`，由 `@intlayer/next-intl`、`@intlayer/react-i18next` 等相容套件設定）：這些呼叫點對使用分析器不可見，因此清除會移除程式碼仍在讀取的欄位。匯入重寫仍保持啟用。
+
+**更早的版本（9.2.1 之前）** 需要 `@intlayer/babel` 以及一個宣告 `intlayerPurgeBabelPlugin` 與 `intlayerMinifyBabelPlugin` 的 `babel.config.js`。該檔案不再需要，可以刪除。
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > 如果在 `optimize` 被設為 `false`、又或是啟用了視覺化編輯器也就是當 `editor.enabled` 設定為了 `true` 時（由於編輯器需要保留欄位名稱以便做後續處理），重新命名這個操作都將會被跳過。
 
+> 在 Next.js 上，當 `@intlayer/swc` 未安裝或無法載入時（Next.js 低於 16.1.0），壓縮同樣會被略過。重寫原始碼存取的正是這個外掛，因此在沒有它的情況下重新命名字典，會讓你的程式碼讀取已不存在的欄位名稱。
+
 > 同理，如果是利用了 `importMode: 'fetch'` 來載入欄位時此過程同樣不適用。因為它們的內容會以原始命名由後端 API 所提供，對客戶端內容隨意重新命名會破壞客戶端與伺服器端的匹配契約。
 
 ### 欄位清除 / Purging (去掉未被引用的欄位內容)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> 與前邊提到的類似，當 `optimize` 是 `false` 或是開啟了視覺化編輯器(`editor.enabled` 取值 `true`) 時，它會選擇跳過對資料的清除操作。
+> 與前邊提到的類似，當 `optimize` 是 `false` 或是開啟了視覺化編輯器(`editor.enabled` 取值 `true`) 時，它會選擇跳過對資料的清除操作。 在 Next.js 上，當 `@intlayer/swc` 不可用以及設定了相容轉接器呼叫方時，還會被額外略過。
 
 > 當檢測到某份程式碼因為異常無法順利解析、又或者當把由 `useIntlayer` 輸出的值以靜態解析器難以預測分析的模式在不同元件中來回丟（比如被打包成物件傳入等而未被進行解構）的時候，它同樣會跳過，以此保守地保留整部字典的全部資訊，避免意外發生。
 

package/docs/zh-TW/intlayer_with_angular_21.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-04-18
 updatedAt: 2026-05-31
-title: "Angular 21 i18n - 翻譯您的應用程式的完整指南"
-description: "告別 i18next。2026 年建構多語言 (i18n) Angular 21 應用程式的完整指南。使用 AI 代理翻譯並優化套件大小、SEO 和效能。"
+title: "Angular 22 i18n - 翻譯您的應用程式的完整指南"
+description: "告別 i18next。2026 年建構多語言 (i18n) Angular 22 應用程式的完整指南。使用 AI 代理翻譯並優化套件大小、SEO 和效能。"
 keywords:
   - 國際化
   - 文件
@@ -13,8 +13,8 @@ slugs:
   - doc
   - environment
   - angular
-applicationTemplate: https://github.com/aymericzip/intlayer-angular-21-template
-applicationShowcase: https://intlayer-angular-21-template.vercel.app/
+applicationTemplate: https://github.com/aymericzip/intlayer-angular-22-template
+applicationShowcase: https://intlayer-angular-22-template.vercel.app/
 history:
   - version: 8.9.0
     date: 2026-05-04
@@ -56,7 +56,7 @@ author: aymericzip
   <Tab label="程式碼" value="code">
 
 <iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-angular-21-template?file=intlayer.config.ts"
+  src="https://ide.intlayer.org/aymericzip/intlayer-angular-22-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"
@@ -67,7 +67,7 @@ author: aymericzip
   <Tab label="展示" value="demo">
 
 <iframe
-  src="https://intlayer-angular-21-template.vercel.app/"
+  src="https://intlayer-angular-22-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="Demo - intlayer-angular-template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -77,7 +77,7 @@ author: aymericzip
   </Tab>
 </Tabs>
 
-在GitHub上查看 [應用程式模板](https://github.com/aymericzip/intlayer-angular-21-template)。
+在GitHub上查看 [應用程式模板](https://github.com/aymericzip/intlayer-angular-22-template)。
 
 <Steps>