@intlayer/docs 9.1.3 → 9.2.0

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/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>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "9.1.3",
+  "version": "9.2.0",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -73,13 +73,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "9.1.3",
-    "@intlayer/core": "9.1.3",
-    "@intlayer/types": "9.1.3"
+    "@intlayer/config": "9.2.0",
+    "@intlayer/core": "9.2.0",
+    "@intlayer/types": "9.2.0"
   },
   "devDependencies": {
-    "@intlayer/api": "9.1.3",
-    "@intlayer/cli": "9.1.3",
+    "@intlayer/api": "9.2.0",
+    "@intlayer/cli": "9.2.0",
     "@types/node": "26.1.2",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",