@intlayer/docs 9.5.6 → 9.5.8

package/docs/zh/cli/infra.md

@@ -0,0 +1,162 @@
+---
+createdAt: 2026-09-21
+updatedAt: 2026-09-21
+title: CLI - Init Infra
+description: 了解如何使用 Intlayer CLI init infra 命令安装桌面应用程序，或使用 Docker（多合一容器或 Docker Compose 堆栈）自行托管 Intlayer CMS。
+keywords:
+  - CLI
+  - 基础设施
+  - 自行托管
+  - 桌面应用
+  - Docker
+  - Docker Compose
+  - CMS
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - infra
+history:
+  - version: 9.5.6
+    date: 2026-09-21
+    changes: "添加 init infra 命令"
+author: aymericzip
+---
+
+# Intlayer CLI Init Infra 命令
+
+## 描述
+
+`init infra` 命令用于在您的机器上设置 Intlayer 基础设施。它会下载适用于您平台的托管安装程序（macOS / Linux 上为 `https://intlayer.org/install.sh`，Windows 上为 `https://intlayer.org/install.ps1`），并在终端中运行，以便完整显示安装程序自身的菜单和进度输出。
+
+安装程序会询问您希望如何运行 Intlayer：
+
+- **桌面应用**：下载适用于您的操作系统和 CPU 的原生控制面板并打开或安装。桌面版本连接至 Intlayer Cloud 后端。
+- **多合一 Docker**：在由单个卷支持的单个容器中运行控制面板 + API + MongoDB + Redis + MinIO。写入包含生成密钥的 `./intlayer.env` 并拉取 `intlayer/cms-all` 镜像。
+- **Docker Compose**：每个服务一个容器，用于可扩展的自行托管。将 `docker-compose.yml` 和 `.env` 写入 `./intlayer/` 并拉取镜像。
+
+托管安装程序是安装流程的唯一真实来源：CLI 运行它而不是重新实现相同步骤，因此 `npx intlayer init infra` 与 `curl -fsSL https://intlayer.org/install.sh | sh` 执行完全相同的操作。
+
+## 用法
+
+```bash packageManager="npm"
+npx intlayer init infra [options]
+```
+
+```bash packageManager="yarn"
+yarn intlayer init infra [options]
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer init infra [options]
+```
+
+```bash packageManager="bun"
+bun x intlayer init infra [options]
+```
+
+`npx intlayer init --interactive` 的检查列表中也提供了相同的步骤，位于 **基础设施 (桌面应用 / 自行托管)** 下。
+
+## 选项
+
+- `-m, --mode <mode>` - 可选。跳过安装程序菜单并直接运行特定模式。接受的值：`desktop`、`docker`（多合一）或 `compose`。任何其他值都会退出并显示错误列出接受的模式。
+
+## 示例
+
+### 以交互方式选择模式
+
+```bash
+npx intlayer init infra
+```
+
+### 安装桌面应用
+
+```bash
+npx intlayer init infra --mode desktop
+```
+
+### 使用多合一容器自行托管
+
+```bash
+npx intlayer init infra --mode docker
+```
+
+### 使用 Docker Compose 自行托管
+
+```bash
+npx intlayer init infra --mode compose
+```
+
+## 示例输出
+
+```bash
+npx intlayer init infra --mode compose
+◇  Installer downloaded
+▸ Fetching docker-compose.yml into ./intlayer
+▸ Writing ./intlayer/.env
+▸ Pulling images
+
+  Everything is installed. Two steps left.
+
+  1. Configure a mailer in:
+
+       ./intlayer/.env
+
+     Either RESEND_API_KEY (resend.com) or the MAIL_SMTP_* block — the first
+     account cannot be verified without a working mailer.
+  2. Start the stack:
+
+       cd ./intlayer && docker compose up -d
+
+  Then open http://localhost:3000 — first boot initialises the
+  datastores, so give it a minute. The first account you create becomes the
+  super admin.
+
+    Logs      docker compose logs -f
+    Stop      docker compose down
+    Upgrade   docker compose pull && docker compose up -d
+```
+
+## 安装程序设置
+
+安装程序会读取一些环境变量，CLI 会原样传递这些变量。在运行命令前请在 shell 中进行设置：
+
+```bash
+INTLAYER_COMPOSE_DIR=./cms npx intlayer init infra --mode compose
+```
+
+| 变量                      | 默认值                    | 适用于  | 描述                                               |
+| ------------------------- | ------------------------- | ------- | -------------------------------------------------- |
+| `INTLAYER_MODE`           | _(询问)_                  | 全部    | `desktop`、`docker` 或 `compose`，与 `--mode` 相同 |
+| `INTLAYER_DOWNLOAD_DIR`   | `~/Downloads`             | desktop | 应用安装程序保存位置                               |
+| `INTLAYER_IMAGE`          | `intlayer/cms-all:latest` | docker  | 要拉取的多合一镜像                                 |
+| `INTLAYER_ENV_FILE`       | `./intlayer.env`          | docker  | 环境文件写入位置                                   |
+| `INTLAYER_CONTAINER_NAME` | `intlayer`                | docker  | 容器名称                                           |
+| `INTLAYER_DATA_VOLUME`    | `intlayer-data`           | docker  | 挂载在 `/data` 的具名卷                            |
+| `INTLAYER_APP_PORT`       | `3000`                    | docker  | 控制面板主机端口                                   |
+| `INTLAYER_API_PORT`       | `3100`                    | docker  | API 主机端口                                       |
+| `INTLAYER_S3_PORT`        | `9000`                    | docker  | MinIO S3 API 主机端口                              |
+| `INTLAYER_CONSOLE_PORT`   | `9001`                    | docker  | MinIO 控制台主机端口                               |
+| `INTLAYER_COMPOSE_DIR`    | `./intlayer`              | compose | 写入 `docker-compose.yml` 和 `.env` 的位置         |
+| `INTLAYER_SELFHOST_REF`   | `main`                    | 两者    | 获取 compose 文件和 env 模板的 Git ref             |
+
+> 端口变量仅更改映射的 **主机** 端。已发布的镜像在控制面板包中预编译了 `http://localhost:3000`、`http://localhost:3100` 和 `http://localhost:9000`，因此除非您构建自己的镜像，否则请保留默认值：请参阅[自行托管指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md#limitations)。
+
+## 环境要求
+
+- **桌面应用** 需要 [Node.js](https://nodejs.org)：该应用内嵌了控制面板服务器，并使用机器自身的 `node` 二进制文件启动。
+- **Docker 模式** 需要 [Docker](https://docs.docker.com/get-docker/)（Windows 上需要带有 WSL 2 后端的 Docker Desktop）。Compose 模式还需要 `docker compose` 插件。
+
+## 注意事项
+
+- 重新运行该命令是安全的：现有的环境文件绝不会被覆盖，因此它也作为升级路径（安装程序会拉取最新镜像并保留您的密钥）。
+- 安装程序会被下载到临时目录中，无论结果如何，退出时都会被删除。
+- 该命令的退出代码即为安装程序的退出代码。如果下载本身失败，CLI 将打印等效的 `curl … | sh`（或 `irm … | iex`）命令，以便您可以直接运行安装程序。
+- Docker 模式仍需要邮件发送服务来发送登录邮件。安装程序完成后，请在生成的环境文件中配置 Resend 或 SMTP：请参阅[全局邮件程序](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md#global-mailer)。
+
+## 相关内容
+
+- [自行托管指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md) - 各模式的架构、首次运行步骤和限制
+- [初始化 Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/init.md) - 父级 `init` 命令及其交互式检查清单
+- [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) - 您刚安装的控制面板的功能

package/docs/zh/cli/init.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-12-30
-updatedAt: 2025-12-30
+updatedAt: 2026-09-21
 title: 初始化 Intlayer
 description: 了解如何在您的项目中初始化 Intlayer。
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - cli
   - init
 history:
+  - version: 9.5.6
+    date: 2026-09-21
+    changes: "添加 init infra 子命令"
   - version: 8.6.4
     date: 2026-03-31
     changes: "添加 --no-gitignore 选项"
@@ -125,6 +128,26 @@ bun x intlayer init --no-gitignore
 
 这将设置所有配置文件，但不会修改您的 `.gitignore`。
 
+### 设置基础设施（桌面应用或自行托管）：
+
+```bash
+npx intlayer init infra
+```
+
+下载并运行在线安装程序（macOS / Linux 上为 `https://intlayer.org/install.sh`，Windows 上为 `install.ps1`），它会询问您希望如何运行 Intlayer：
+
+- **桌面应用** - 在您的机器上安装原生控制面板，连接到 Intlayer Cloud。
+- **多合一 Docker** - 在单个容器中包含控制面板 + API + MongoDB + Redis + MinIO。
+- **Docker Compose** - 每个服务一个容器，用于可扩展的自行托管。
+
+使用 `--mode` 跳过菜单：
+
+```bash
+npx intlayer init infra --mode compose
+```
+
+`npx intlayer init --interactive` 也提供了相同的步骤。有关安装程序设置，请参阅 [`init infra` 参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/infra.md)，有关各模式设置的内容，请参阅[自行托管指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)。
+
 ## 输出示例：
 
 ```bash

package/docs/zh/cli/upgrade.md

@@ -0,0 +1,125 @@
+---
+createdAt: 2026-09-23
+updatedAt: 2026-09-23
+title: CLI - 升级 Intlayer 软件包
+description: 了解如何使用 Intlayer CLI upgrade 命令列出项目或 monorepo 中的每个 Intlayer 软件包，并将它们升级到最新版本。
+keywords:
+  - CLI
+  - Upgrade
+  - 升级
+  - Packages
+  - Monorepo
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - upgrade
+history:
+  - version: 9.5.8
+    date: 2026-09-23
+    changes: "添加 upgrade 命令"
+author: aymericzip
+---
+
+# 升级 Intlayer 软件包
+
+```bash packageManager="npm"
+npx intlayer upgrade
+```
+
+```bash packageManager="yarn"
+yarn intlayer upgrade
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer upgrade
+```
+
+```bash packageManager="bun"
+bun x intlayer upgrade
+```
+
+`upgrade` 命令会列出项目中每个 `package.json`（包括 monorepo 工作区）中声明的 Intlayer 软件包，并将它们升级到已发布的最新版本。它独立运行与 `intlayer init` 相同的软件包升级步骤。
+
+## 参数:
+
+- `--project-root [projectRoot]` - 可选。项目根目录。默认情况下，命令从当前工作目录上方最近的 `package.json` 开始。
+- `--dry-run` - 可选。列出软件包及其目标版本，而不修改任何文件。
+- `--tag <tag>` - 可选。要升级到的 npm dist-tag（例如 `canary`）。默认为 `latest`。
+
+## 它的工作原理:
+
+1. **列出 Intlayer 软件包** - 扫描项目的每个 `package.json`（跳过 `node_modules` 和构建输出），查找 `intlayer`、`@intlayer/*`、`*-intlayer` 和 `intlayer-*` 依赖项及 devDependencies。
+2. **获取目标版本** - 从 npm registry 读取每个软件包所选 dist-tag（默认为 `latest`）的版本。
+3. **重写版本范围** - 就地更新每个过期的版本范围，保留其操作符（`^`、`~` 或无）和文件缩进。
+4. **单次安装** - 使用拥有锁文件的包管理器，从工作区根目录（带有锁文件的最近目录）执行一次安装：
+
+| 锁文件                         | 命令           |
+| ------------------------------ | -------------- |
+| `bun.lock` / `bun.lockb`       | `bun install`  |
+| `pnpm-lock.yaml`               | `pnpm install` |
+| `yarn.lock`                    | `yarn install` |
+| `package-lock.json` 或无锁文件 | `npm install`  |
+
+如果不存在锁文件，则在回退到 npm 之前会先使用 `package.json` 中的 `packageManager` 字段（例如 `"bun@1.2.0"`）。
+
+未指向 registry 的范围（例如 `workspace:*`、`file:`、`link:`、`catalog:` 或 git URL）绝不会被修改。
+
+## 示例:
+
+### 列出可用的升级而不应用它们:
+
+```bash packageManager="npm"
+npx intlayer upgrade --dry-run
+```
+
+```bash packageManager="yarn"
+yarn intlayer upgrade --dry-run
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer upgrade --dry-run
+```
+
+```bash packageManager="bun"
+bun x intlayer upgrade --dry-run
+```
+
+### 升级到 canary 版本:
+
+```bash packageManager="npm"
+npx intlayer upgrade --tag canary
+```
+
+```bash packageManager="yarn"
+yarn intlayer upgrade --tag canary
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer upgrade --tag canary
+```
+
+```bash packageManager="bun"
+bun x intlayer upgrade --tag canary
+```
+
+## 示例输出:
+
+```bash
+npx intlayer upgrade
+Intlayer packages:
+  package.json
+    intlayer ^9.0.0 → ^9.5.7
+  apps/web/package.json
+    next-intlayer ^9.5.7 (latest)
+    vite-intlayer ~9.2.0 → ~9.5.7
+Running bun install...
+✓ Upgraded 2 Intlayer dependencies to latest
+```
+
+## 注意事项:
+
+- 从代码仓库根目录运行该命令以升级所有工作区。从某个工作区运行它以仅升级该工作区。
+- 无法获取版本的软件包（离线、私有或未发布的软件包）会被列出并保持不变。
+- 如果安装失败，已升级的范围会保留在 `package.json` 中。请手动运行包管理器的安装命令。

package/docs/zh/dictionary/html.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-01-20
-updatedAt: 2026-03-24
+updatedAt: 2026-09-21
 title: HTML 内容
 description: 了解如何在 Intlayer 中声明和使用带有自定义组件的 HTML 内容。按照本指南在你的国际化项目中嵌入具有动态组件替换功能的丰富类 HTML 内容。
 keywords:
@@ -13,6 +13,8 @@ keywords:
   - React
   - Vue
   - Svelte
+  - Remix
+  - Astro
 slugs:
   - doc
   - concept
@@ -235,6 +237,83 @@ const myContent = html(
     ```
 
   </Tab>
+  <Tab label="Remix" value="remix">
+    在 Remix 3 中，HTML 节点解析为 HTML 字符串。使用 Remix JSX 的 `innerHTML` 属性注入它，或在 `html-template` 视图中使用 `html.raw`。
+
+    ```tsx fileName="src/views/home.tsx"
+    import { useIntlayer } from "remix-intlayer";
+
+    export const HomePage = () => () => {
+      const { myHtmlContent } = useIntlayer("app");
+
+      return <div innerHTML={myHtmlContent.value} />;
+    };
+    ```
+
+    ```ts fileName="src/views/home.ts"
+    import { html } from "remix/html-template";
+    import { useIntlayer } from "remix-intlayer";
+
+    export const renderHomePage = () => {
+      const { myHtmlContent } = useIntlayer("app");
+
+      return html.raw`<div>${myHtmlContent.value}</div>`;
+    };
+    ```
+
+    > Remix 默认会转义插值。`innerHTML` 和 `html.raw` 是两个例外选项，这正是 HTML 字符串所需要的。
+
+    使用 `.use()` 方法覆盖标签或映射自定义组件。覆盖是返回 HTML 字符串的函数：
+
+    ```tsx
+    <div
+      innerHTML={myHtmlContent.use({
+        p: ({ children }) => `<p class="prose">${children}</p>`,
+        CustomLink: ({ children }) => `<a href="/details">${children}</a>`,
+      })}
+    />
+    ```
+
+  </Tab>
+  <Tab label="Astro" value="astro">
+    在 Astro 中，HTML 节点解析为 HTML 字符串。使用模板中的 `set:html` 指令注入它，或在客户端 `<script>` 中使用 `innerHTML`。
+
+    ```astro fileName="src/pages/index.astro"
+    ---
+    import { useIntlayer } from "astro-intlayer";
+
+    const { myHtmlContent } = useIntlayer("app");
+    ---
+
+    <div set:html={myHtmlContent.value} />
+    ```
+
+    ```astro fileName="src/components/Content.astro"
+    <div id="content"></div>
+
+    <script>
+      import { useIntlayer } from "astro-intlayer";
+
+      const { myHtmlContent } = useIntlayer("app");
+
+      document.querySelector("#content")!.innerHTML = myHtmlContent.value;
+    </script>
+    ```
+
+    > Astro 默认会转义 `{表达式}`。`set:html` 是例外选项，这正是 HTML 字符串所需要的。
+
+    使用 `.use()` 方法覆盖标签或映射自定义组件。覆盖是返回 HTML 字符串的函数：
+
+    ```astro
+    <div
+      set:html={myHtmlContent.use({
+        p: ({ children }) => `<p class="prose">${children}</p>`,
+        CustomLink: ({ children }) => `<a href="/details">${children}</a>`,
+      })}
+    />
+    ```
+
+  </Tab>
 </Tabs>
 
 ## 使用 `HTMLProvider` 的全局配置
@@ -470,6 +549,40 @@ const myContent = html(
     > 动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。
 
   </Tab>
+  <Tab label="Remix" value="remix">
+
+    Remix 没有组件树来承载 provider，因此配置在服务器启动时作为单例安装一次。它配置由 `useHTMLRenderer()` 返回的渲染器。由 `useIntlayer` 返回的 `html` 节点按原样渲染；通过 `.use()` 为每个节点覆盖其标签。
+
+    ```typescript fileName="src/router.ts"
+    import { installIntlayerHTML } from "remix-intlayer/html";
+
+    installIntlayerHTML({
+      renderHTML: (html) => html.replaceAll("<p>", '<p class="prose">'),
+    });
+    ```
+
+    > 使用 `installIntlayerHTMLDynamic(async () => …)` 延迟加载渲染器本身；加载器仅在第一次调用时运行。
+
+  </Tab>
+  <Tab label="Astro" value="astro">
+
+    Astro 没有组件树来承载 provider，因此配置在中间件（服务器）和客户端 `<script>`（浏览器）中作为单例安装一次。它配置由 `useHTMLRenderer()` 返回的渲染器。由 `useIntlayer` 返回的 `html` 节点按原样渲染；通过 `.use()` 为每个节点覆盖其标签。
+
+    ```typescript fileName="src/middleware.ts"
+    import { installIntlayerHTML } from "astro-intlayer/html";
+    import { defineMiddleware } from "astro:middleware";
+
+    // 服务器启动时运行一次；Intlayer 中间件本身由集成在此文件之前注册。
+    installIntlayerHTML({
+      renderHTML: (html) => html.replaceAll("<p>", '<p class="prose">'),
+    });
+
+    export const onRequest = defineMiddleware((_context, next) => next());
+    ```
+
+    > 使用 `installIntlayerHTMLDynamic(async () => …)` 延迟加载渲染器本身；加载器仅在第一次调用时运行。
+
+  </Tab>
 </Tabs>
 
 ### 手动渲染与高级工具
@@ -642,15 +755,69 @@ const myContent = html(
     ```
 
   </Tab>
+  <Tab label="Remix" value="remix">
+    #### `useHTMLRenderer()` Hook
+
+    获取由 `installIntlayerHTML()` 预配置的渲染器函数。它返回一个 HTML 字符串。
+
+    ```tsx
+    import { useHTMLRenderer } from "remix-intlayer/html";
+
+    const renderHTML = useHTMLRenderer();
+
+    return <div innerHTML={renderHTML("<p>Hello <strong>World</strong></p>")} />;
+    ```
+
+    #### `renderHTML()` 实用工具
+
+    忽略全局配置的独立实用工具。
+
+    ```tsx
+    import { renderHTML } from "remix-intlayer/html";
+
+    const html = renderHTML("<p>Hello</p>");
+    ```
+
+  </Tab>
+  <Tab label="Astro" value="astro">
+    #### `useHTMLRenderer()` Hook
+
+    获取由 `installIntlayerHTML()` 预配置的渲染器函数。它返回一个 HTML 字符串。
+
+    ```astro
+    ---
+    import { useHTMLRenderer } from "astro-intlayer/html";
+
+    const renderHTML = useHTMLRenderer();
+    ---
+
+    <div set:html={renderHTML("<p>Hello <strong>World</strong></p>")} />
+    ```
+
+    #### `renderHTML()` 实用工具
+
+    忽略全局配置的独立实用工具。
+
+    ```astro
+    ---
+    import { renderHTML } from "astro-intlayer/html";
+
+    const html = renderHTML("<p>Hello</p>");
+    ---
+
+    <div set:html={html} />
+    ```
+
+  </Tab>
 </Tabs>
 
 ## 选项参考
 
 这些选项可以传递给 `HTMLProvider`、`HTMLRenderer`、`useHTMLRenderer` 和 `renderHTML`。
 
-| 选项         | 类型                  | 默认   | 说明                                                                               |
-| :----------- | :-------------------- | :----- | :--------------------------------------------------------------------------------- |
-| `components` | `Record<string, any>` | `{}`   | 一个将 HTML 标签或自定义组件名称映射到对应组件的映射表。                           |
-| `renderHTML` | `Function`            | `null` | 一个自定义渲染函数，用于完全替换默认的 HTML 解析器（仅适用于 Vue/Svelte 提供器）。 |
+| 选项         | 类型                  | 默认   | 说明                                                                             |
+| :----------- | :-------------------- | :----- | :------------------------------------------------------------------------------- |
+| `components` | `Record<string, any>` | `{}`   | 一个将 HTML 标签或自定义组件名称映射到对应组件的映射表。                         |
+| `renderHTML` | `Function`            | `null` | 完全替换默认 HTML 解析器的自定义渲染函数（Vue、Svelte、Remix 和 Astro 提供者）。 |
 
 > 注意：对于 React 和 Preact，标准 HTML 标签会自动提供。只有当你想覆盖它们或添加自定义组件时，才需要传入 `components` prop。