@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/vi/self_hosting.md

@@ -0,0 +1,349 @@
+---
+createdAt: 2026-06-30
+updatedAt: 2026-06-30
+title: Tự host Intlayer
+description: Chạy một phiên bản Intlayer hoàn chỉnh trên hạ tầng của riêng bạn chỉ với một lệnh duy nhất. Không yêu cầu tài khoản Intlayer Cloud.
+keywords:
+  - Self-Hosting
+  - Docker
+  - Docker Compose
+  - Intlayer
+  - CMS
+  - Installation
+  - Infrastructure
+slugs:
+  - doc
+  - self-hosting
+author: aymericzip
+---
+
+# Tự host Intlayer
+
+Intlayer có thể chạy hoàn toàn trên hạ tầng của riêng bạn — không yêu cầu tài khoản Intlayer Cloud. Chỉ một lệnh duy nhất sẽ khởi động một stack sẵn sàng cho production:
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Trình cài đặt sẽ tải xuống `docker-compose.yml` và `.env`, tự động tạo các secret cần thiết, và khởi động tất cả các container với `docker compose up -d`.
+
+## Mục lục
+
+<TOC/>
+
+---
+
+## Kiến trúc
+
+```
+                ┌─────────────────────────────┐
+ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
+                └─────────────────────────────┘   │ VITE_BACKEND_URL
+                ┌─────────────────────────────┐   │
+                │  backend (Fastify/Bun)  :3100│ ◀─┘
+                └──────────────┬──────────────┘
+          ┌──────────┬─────────┼──────────┬───────────┐
+          ▼          ▼         ▼          ▼           ▼
+     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium
+     (1-node RS)             (S3 API)     (SMTP)        (in-image)
+                             minio:9001   mailpit:8025
+                             (console)    (web UI)
+```
+
+Chromium (được sử dụng để tạo ảnh chụp màn hình Puppeteer) được đóng gói bên trong image backend — không cần container riêng.
+
+---
+
+## Điều kiện tiên quyết
+
+- **Docker** ≥ 24 và **Docker Compose** ≥ v2. Nếu thiếu một trong hai, trình cài đặt sẽ in liên kết cài đặt và thoát.
+- Các cổng `3000`, `3100`, `8025`, `9000`, và `9001` phải khả dụng trên host.
+- Host chạy Linux hoặc macOS (hoặc WSL2 trên Windows).
+
+---
+
+## Bắt đầu nhanh
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Những gì trình cài đặt thực hiện:
+
+1.  Kiểm tra xem `docker` và `docker compose` có tồn tại không.
+2.  Tải xuống `docker-compose.yml` và `.env.example` vào `./intlayer/`.
+3.  Nếu không có `.env` tồn tại, sao chép file ví dụ và tạo các secret ngẫu nhiên cho `BETTER_AUTH_SECRET`, `S3_ACCESS_KEY_ID`, và `S3_SECRET_ACCESS_KEY` thông qua `openssl rand`.
+4.  Chạy `docker compose pull` + `docker compose up -d`.
+5.  In các URL: dashboard `:3000`, API `:3100`, UI email `:8025`, console MinIO `:9001`.
+
+Sau khi stack hoạt động, mở **http://localhost:3000** và tạo tài khoản đầu tiên của bạn.
+
+---
+
+## Các dịch vụ
+
+| Dịch vụ     | Image                                      | Cổng Host                      | Mục đích                                                         |
+| ----------- | ------------------------------------------ | ------------------------------ | ---------------------------------------------------------------- |
+| **app**     | được xây dựng từ `apps/app/Dockerfile`     | `3000`                         | Dashboard TanStack Start (UI của CMS)                            |
+| **backend** | được xây dựng từ `apps/backend/Dockerfile` | `3100`                         | API REST Fastify (endpoint `/health`)                            |
+| **mongo**   | `mongo:7`                                  | nội bộ                         | Bộ nhân bản một node (`rs0`)                                     |
+| **redis**   | `redis:7-alpine`                           | nội bộ                         | Hàng đợi công việc (BullMQ) và caching (ioredis)                 |
+| **minio**   | `minio/minio`                              | `9000` (S3), `9001` (console)  | Lưu trữ đối tượng tương thích S3 cho avatar và ảnh chụp màn hình |
+| **mailpit** | `axllent/mailpit`                          | `1025` (SMTP), `8025` (web UI) | Nơi nhận email giao dịch cục bộ                                  |
+
+Các cổng nội bộ (mongo, redis) không được phơi bày ra host theo mặc định.
+
+> Cổng MinIO `9000` phải có thể truy cập được bởi trình duyệt vì các tài sản được tải lên (avatars, ảnh chụp màn hình) được tải trực tiếp từ `S3_PUBLIC_URL=http://localhost:9000/intlayer`.
+
+---
+
+## Các biến môi trường
+
+Trình cài đặt tạo ra một file `.env` sẵn sàng để sử dụng. Bảng dưới đây mô tả từng biến.
+
+### Bắt buộc (tự động tạo hoặc được nhắc nhở)
+
+| Biến                   | Ví dụ                                           | Mô tả                                             |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------------- |
+| `NODE_ENV`             | `production`                                    | Môi trường runtime                                |
+| `PORT`                 | `3100`                                          | Cổng lắng nghe của Backend                        |
+| `BACKEND_URL`          | `http://localhost:3100`                         | URL công khai của API backend                     |
+| `APP_URL`              | `http://localhost:3000`                         | URL công khai của dashboard                       |
+| `DOMAIN`               | `localhost`                                     | Miền cookie                                       |
+| `MONGODB_URI`          | `mongodb://mongo:27017/intlayer?replicaSet=rs0` | URI kết nối MongoDB đầy đủ                        |
+| `REDIS_URL`            | `redis://redis:6379`                            | URL kết nối Redis                                 |
+| `BETTER_AUTH_SECRET`   | _(được tạo)_                                    | Secret 32-byte để ký session                      |
+| `MAIL_PROVIDER`        | `smtp`                                          | Phương thức gửi mail: `smtp` hoặc `resend`        |
+| `MAIL_SMTP_HOST`       | `mailpit`                                       | Tên host SMTP (tên container Mailpit)             |
+| `MAIL_SMTP_PORT`       | `1025`                                          | Cổng SMTP                                         |
+| `MAIL_FROM`            | `Intlayer <no-reply@localhost>`                 | Địa chỉ người gửi                                 |
+| `S3_ENDPOINT`          | `http://minio:9000`                             | Endpoint tương thích S3                           |
+| `S3_PUBLIC_URL`        | `http://localhost:9000/intlayer`                | URL công khai để trình duyệt tải tài sản          |
+| `S3_BUCKET_NAME`       | `intlayer`                                      | Tên bucket                                        |
+| `S3_ACCESS_KEY_ID`     | _(được tạo)_                                    | Khóa truy cập MinIO                               |
+| `S3_SECRET_ACCESS_KEY` | _(được tạo)_                                    | Khóa bí mật MinIO                                 |
+| `VITE_BACKEND_URL`     | `http://localhost:3100`                         | URL backend được tích hợp vào dashboard khi build |
+| `VITE_DOMAIN`          | `localhost`                                     | Miền được tích hợp vào dashboard khi build        |
+
+### Tùy chọn (tính năng sẽ suy giảm khi không có)
+
+| Biến                                                     | Tính năng                                                      |
+| -------------------------------------------------------- | -------------------------------------------------------------- |
+| `OPENAI_API_KEY`                                         | Dịch thuật và kiểm tra nội dung có sự hỗ trợ của AI            |
+| `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_*` | Quản lý thanh toán và đăng ký                                  |
+| `RESEND_API_KEY`                                         | Email giao dịch qua Resend (ghi đè Mailpit khi được thiết lập) |
+| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`               | Đăng nhập GitHub OAuth                                         |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`               | Đăng nhập Google OAuth                                         |
+| `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`               | Đăng nhập GitLab OAuth                                         |
+| `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`         | Đăng nhập Microsoft OAuth                                      |
+| `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`           | Đăng nhập LinkedIn OAuth                                       |
+| `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`         | Đăng nhập Atlassian OAuth                                      |
+
+---
+
+## Kết nối dự án Intlayer của bạn
+
+Khi stack đang chạy, hãy trỏ dự án của bạn đến backend và dashboard được tự host thay vì `intlayer.org`.
+
+### Cấu hình dự án
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+
+    /**
+     * URL của dashboard CMS được tự host.
+     * Mặc định: https://app.intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL, // ví dụ: http://localhost:3000
+
+    /**
+     * URL của API backend được tự host.
+     * Mặc định: https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL, // ví dụ: http://localhost:3100
+  },
+};
+
+export default config;
+```
+
+Thiết lập các biến môi trường trong file `.env` của dự án bạn:
+
+```sh
+INTLAYER_CMS_URL=http://localhost:3000
+INTLAYER_BACKEND_URL=http://localhost:3100
+INTLAYER_CLIENT_ID=<your-client-id>
+INTLAYER_CLIENT_SECRET=<your-client-secret>
+```
+
+Tạo thông tin truy cập trong dashboard được tự host của bạn dưới mục **Projects → Access keys** tại `http://localhost:3000/projects`.
+
+### SDK `@intlayer/api`
+
+Khi sử dụng SDK `@intlayer/api` theo cách lập trình, hãy truyền `backendURL` một cách rõ ràng:
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
+  },
+});
+
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+```
+
+---
+
+## Nâng cấp
+
+Chạy lại trình cài đặt trên một triển khai hiện có sẽ thực hiện nâng cấp cuốn chiếu (rolling upgrade):
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Thao tác này sẽ kéo các image mới nhất và khởi động lại các container với `docker compose pull && docker compose up -d`. Các volume hiện có (`mongo-data`, `redis-data`, `minio-data`) được bảo toàn — không mất dữ liệu.
+
+Để nâng cấp thủ công từ bên trong thư mục `./intlayer/`:
+
+```sh
+docker compose pull
+docker compose up -d
+```
+
+---
+
+## Sao lưu và phục hồi
+
+Tất cả dữ liệu bền vững nằm trong ba Docker volume được đặt tên.
+
+### Sao lưu
+
+```sh
+docker run --rm \
+  -v intlayer_mongo-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/mongo-data.tar.gz /data
+
+docker run --rm \
+  -v intlayer_redis-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/redis-data.tar.gz /data
+
+docker run --rm \
+  -v intlayer_minio-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/minio-data.tar.gz /data
+```
+
+### Phục hồi
+
+```sh
+docker run --rm \
+  -v intlayer_mongo-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar xzf /backup/mongo-data.tar.gz -C /
+
+# Lặp lại cho redis-data và minio-data
+```
+
+---
+
+## Sử dụng reverse proxy (Nginx / Caddy)
+
+Đối với các triển khai production, hãy đặt một reverse proxy phía trước các container app và backend thay vì phơi bày chúng trực tiếp.
+
+### Ví dụ 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;
+    }
+}
+```
+
+Cập nhật các biến `.env` sau để khớp với các miền công khai của bạn:
+
+```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
+```
+
+> Các biến `VITE_*` được tích hợp vào image dashboard tại thời điểm build. Nếu bạn thay đổi chúng sau khi image được build, bạn cần build lại image `app` (`docker compose build app`) hoặc sử dụng cấu hình runtime injection.
+
+---
+
+## Khắc phục sự cố
+
+### Backend bị crash-loop khi khởi động lần đầu
+
+MongoDB và Redis phải hoạt động tốt trước khi backend khởi động. File compose sử dụng `depends_on` với `condition: service_healthy`. Nếu bạn thấy backend khởi động lại liên tục, hãy kiểm tra xem healthcheck của `mongo` và `redis` có vượt qua không:
+
+```sh
+docker compose ps
+docker compose logs mongo
+docker compose logs redis
+```
+
+### Dashboard không thể kết nối tới API
+
+Xác minh rằng `VITE_BACKEND_URL` khớp với URL mà backend có thể truy cập được từ **trình duyệt** (không phải mạng Docker). Nếu bạn đã thay đổi cổng backend hoặc thêm reverse proxy, hãy build lại image dashboard:
+
+```sh
+docker compose build app
+docker compose up -d app
+```
+
+### Email không gửi được
+
+Theo mặc định, tất cả email gửi đi được Mailpit thu nhận. Mở `http://localhost:8025` để xem các tin nhắn đã gửi. Để gửi email thật, hãy đặt `MAIL_PROVIDER=resend` và `RESEND_API_KEY=<your-key>` trong `.env`, sau đó khởi động lại backend:
+
+```sh
+docker compose restart backend
+```
+
+### Thiếu MinIO bucket
+
+Nếu dịch vụ một lần chạy `minio-init` không chạy (hoặc chạy trước khi MinIO sẵn sàng), hãy tạo bucket thủ công:
+
+```sh
+docker compose run --rm minio-init
+```
+
+---
+
+## Các liên kết hữu ích
+
+- [Tài liệu Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_CMS.md)
+- [Tham chiếu cấu hình](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md)
+- [CMS SDK — `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)

package/docs/zh/CI_CD.md

@@ -28,7 +28,7 @@ Intlayer 允许自动生成内容声明文件的翻译。根据您的工作流
 
 ## 使用 CMS
 
-使用 Intlayer，您可以采用一种工作流程，只在本地声明单一语言环境，而所有翻译内容则通过 CMS 远程管理。这使内容和翻译完全脱离代码库，为内容编辑者提供更大的灵活性，并支持热内容重载（无需重建应用即可应用更改）。
+使用 Intlayer，你可以采用一种工作流程，其中只需在本地声明单一语言环境，而所有翻译都通过 CMS 远程管理。这允许内容和翻译与代码库完全分离，为内容编辑提供更多灵活性，并支持 Live Sync（无需重新构建应用程序即可应用更改）。
 
 ### 示例配置
 

package/docs/zh/autoFill.md

@@ -28,6 +28,53 @@ history:
 author: aymericzip
 ---
 
+# 填充内容声明文件翻译
+
+**在 CI 中自动填充内容声明文件**是加快开发工作流程的一种方式。
+
+## 理解行为
+
+`fill` 命令包括两种模式：
+
+- **Complete**: 自动为每个区域设置填充所有缺失的内容，并编辑当前文件或指定的另一个文件。也就是说，完整模式将跳过已翻译内容的翻译。
+- **Review**: 自动为每个区域设置填充**所有**内容，并为特定文件或指定的另一个文件生成。
+
+fill 命令将处理您的所有区域内容声明文件。也就是说，它不会处理来自 CMS 的远程内容。CMS 包含其自己的翻译管理。
+如果您使用插件，如 `@intlayer/sync-json-plugin`，Intlayer 将把 JSON 文件转换为区域内容声明文件。也就是说，它们将由 `fill` 命令处理。
+
+新生成的文件包含一个 `filled` 指令作为字典元数据。此指令将由 Intlayer 用来判断文件是否已自动填充，以及如果存在则跳过此文件不再进行翻译。
+
+Intlayer 还将考虑以下自动填充指令：
+
+- 来自您的 `.content.{ts|js|json}` → `fill` 指令
+- 来自您的配置文件 `.intlayer.config.ts` → `dictionary.fill` 指令
+- 否则将默认设置为 `true`
+
+对于按区域设置的内容声明文件，`true` 指令将被替换为 `./{{fileName}}.fill.content.json`。这是因为按区域设置的内容声明文件无法接收额外的本地化内容。因此它将生成一个新文件，以不覆盖现有文件。
+
+## 默认行为
+
+默认情况下，`fill` 全局设置为 `true`，这意味着 Intlayer 将自动填充所有内容文件并编辑文件本身。这个行为可以通过以下几种方式自定义：
+
+### 全局配置选项
+
+1. **`fill: true` (默认)** - 自动填充所有语言并编辑当前文件
+2. **`fill: false`** - 禁用此内容文件的自动填充
+3. **`fill: "./relative/path/to/file"`** - 创建/更新指定的文件，不编辑当前文件，指向基于当前文件位置解析的相对路径
+4. **`fill: "/absolute/path/to/file"`** - 创建/更新指定的文件，不编辑当前文件，指向基于基目录位置解析的相对路径（配置文件 `.intlayer.config.ts` 中的 `baseDir` 字段）
+5. **`fill: "C:\\absolute\path\to\file"`** - 创建/更新指定的文件，不编辑当前文件，指向基于你的操作系统解析的绝对路径
+6. **`fill: { [key in Locales]?: string }`** - 为每个语言创建/更新指定的文件
+
+### v7 行为更改
+
+在 v7 中，`fill` 命令的行为已更新：
+
+- **`fill: true`** - 使用所有语言的已填充内容重写当前文件
+- **`fill: "path/to/file"`** - 填充指定文件而不修改当前文件
+- **`fill: false`** - 完全禁用自动填充
+
+使用路径选项写入另一个文件时，填充机制通过内容声明文件之间的 _主从_ 关系工作。主（master）文件作为真实来源，当它被更新时，Intlayer 将自动将这些更改应用到由路径指定的派生（填充）声明文件。
+
 # 自动填充内容声明文件翻译
 
 **自动填充内容声明文件** 是加快开发工作流程的一种方式。
@@ -88,6 +135,40 @@ Intlayer 将自动生成派生的声明文件，路径为 `src/components/exampl
 
 之后，这两个声明文件将合并为一个字典，可以通过标准的 `useIntlayer("example")` 钩子（React）或组合函数（Vue）访问。
 
+## 全局配置
+
+您可以在 `intlayer.config.ts` 文件中配置全局自动填充配置。
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // 为所有字典自动生成缺失的翻译
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // 为所有字典自动生成缺失的翻译，如使用 "./{{fileName}}.content.json"
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+您仍然可以使用内容文件中的 `fill` 字段按字典进行微调。Intlayer 将首先考虑每个字典的配置，然后回退到全局配置。
+
 ## 自动填充文件格式
 
 推荐的自动填充声明文件格式是 **JSON**，这有助于避免格式限制。然而，Intlayer 也支持 `.ts`、`.js`、`.mjs`、`.cjs` 及其他格式。

package/docs/zh/benchmark/solid.md

@@ -117,6 +117,28 @@ history:
 - **分层静态 (Scoped static)**: 保持代码有序（逻辑分离），无需复杂的额外网络请求。
 - **分层动态 (Scoped dynamic)**: _代码拆分_ 和性能的最佳方法。通过仅加载当前视图和活动语言所需的内容来最小化内存使用。
 
+### 我测量的内容：
+
+我在实际浏览器中为每个技术栈运行相同的多语言应用，然后记录了实际显示的内容和花费的时间。大小是在**正常 Web 压缩后**报告的，因为这更接近人们下载的内容，而不是原始源代码计数。
+
+- **国际化库大小**：在捆绑、树形摇晃和最小化后，i18n 库的大小是空组件中提供程序 + hooks/基元代码的大小。它不包括加载翻译文件。它回答了在您的内容进入之前库的成本。
+
+- **每页 JavaScript**：对于每个基准测试路由，浏览器在该访问中提取的脚本量，在套件中的页面之间平均（以及在报告汇总的语言之间）。沉重的页面是缓慢的页面。
+
+- **来自其他语言的泄漏**：这是同一页面但以另一种语言显示的内容，会被错误地加载到已审核页面中。此内容是不必要的，应该避免。（例如 `/fr/about` 页面内容在 `/en/about` 页面包中）
+
+- **来自其他路由的泄漏**：对于应用中的**其他屏幕**也是相同的概念：当您只打开一个页面时，它们的副本是否会随之而来。（例如 `/en/about` 页面内容在 `/en/contact` 页面包中）。高分数表示分割较弱或包过于宽泛。
+
+- **平均组件包大小**：常见的 UI 部分被**一次一个**测量，而不是隐藏在一个巨大的应用数字中。它显示国际化是否悄悄地增加了日常组件的大小。例如，如果您的组件重新渲染，它将从内存加载所有该数据。将一个巨大的 JSON 附加到任何组件就像连接一个大量未使用数据的仓库，这会减慢您组件的性能。
+
+- **语言切换响应性**：我使用应用自己的控件翻转语言，并计时直到页面明显切换需要多长时间，这是访问者会注意到的，而不是实验室微步骤。
+
+- **语言更改后的渲染工作**：一个更狭隘的后续：界面为新语言重新绘制需要花费多少工作量，一旦切换进行中。当"感知"时间和框架成本不同时很有用。
+
+- **初始页面加载时间**：从导航到浏览器认为页面对我测试的场景完全加载。适合比较冷启动。
+
+- **水合时间**：当应用公开它时，客户端花费多长时间将服务器 HTML 转换为您实际可以点击的内容。表格中的破折号表示该实现在此基准测试中没有提供可靠的水合数据。
+
 ## GitHub 星数
 
 GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力指标。虽然星数不是技术质量的直接衡量标准，但它们反映了有多少开发人员发现该项目有用、关注其进展并可能采用它。在评估项目价值时，星数有助于比较不同方案的吸引力，并提供对生态系统增长的见解。

package/docs/zh/benchmark/svelte.md

@@ -116,6 +116,28 @@ history:
 - **分层静态 (Scoped static)**: 保持代码有序（逻辑分离），无需复杂的额外网络请求。
 - **分层动态 (Scoped dynamic)**: _代码拆分_ 和性能的最佳方法。通过仅加载当前视图和活动语言所需的内容来最小化内存使用。
 
+### 我测量了什么:
+
+我在真实浏览器中为每个栈运行相同的多语言应用，然后记录了实际在网络上显示的内容以及花费的时间。大小报告是**在正常网络压缩后**的，因为这比原始源代码计数更接近人们实际下载的内容。
+
+- **国际化库大小**：在打包、tree-shaking 和 minification 之后，i18n 库的大小是空组件中提供程序 + 存储代码的大小。它不包括翻译文件的加载。它回答了库在你的内容进入之前有多昂贵的问题。
+
+- **每页 JavaScript**：对于每个基准测试路由，浏览器在该访问中拉取多少脚本，在套件中的页面之间平均（以及在报告汇总的区域设置之间）。页面重则加载慢。
+
+- **其他区域设置的泄漏**：同一页面的内容但以另一种语言形式，会被错误地加载到审核页面中。此内容是不必要的，应该避免。（例如 `/fr/about` 页面内容出现在 `/en/about` 页面包中）
+
+- **其他路由的泄漏**：对于**应用中的其他屏幕**也是同样的想法：当你只打开一个页面时，它们的副本是否会被带入。（例如 `/en/about` 页面内容出现在 `/en/contact` 页面包中）。高分数表示分割较弱或包范围过宽。
+
+- **平均组件包大小**：常见的 UI 组件**一次一个**地测量，而不是隐藏在一个巨大的应用数字中。它展示了国际化是否悄悄地膨胀了日常组件。例如，如果你的组件重新渲染，它会从内存中加载所有这些数据。将一个巨大的 JSON 附加到任何组件就像连接一个大的未使用数据存储，这会减慢你的组件性能。
+
+- **语言切换响应性**：我使用应用自身的控件翻转语言，并计时直到页面清晰地切换为止，这是访问者会注意到的，而不是实验室微步骤。
+
+- **语言更改后的渲染工作**：一个更窄的后续跟进：一旦切换进行中，界面为新语言重新绘制花费了多少工作量。在"感受"时间和框架成本不一致时很有用。
+
+- **初始页面加载时间**：从导航到浏览器认为我测试的场景中的页面完全加载。适合比较冷启动。
+
+- **Hydration 时间**：当应用暴露它时，客户端花费多长时间将服务器 HTML 转换为你实际可以点击的内容。表格中的破折号表示该实现在此基准测试中没有提供可靠的 hydration 数字。
+
 ## GitHub 星数
 
 GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力指标。虽然星数不是技术质量的直接衡量标准，但它们反映了有多少开发人员发现该项目有用、关注其进展并可能采用它。在评估项目价值时，星数有助于比较不同方案的吸引力，并提供对生态系统增长的见解。

package/docs/zh/benchmark/tanstack.md

@@ -124,6 +124,28 @@ history:
 - **Scoped static (局部静态)**: 保持代码组织良（逻辑分离），且无需复杂的额外网络请求。
 - **Scoped dynamic (局部动态)**: 代码分割和性能的最佳方案。通过仅加载当前视图和活动语言环境所需的内容来最小化内存占用。
 
+### 我测量的内容：
+
+我在真实浏览器中为每个技术栈运行相同的多语言应用，然后记录了实际传输的内容以及所花费的时间。大小是在**正常网络压缩后**报告的，因为这比原始源代码数更接近人们下载的内容。
+
+- **国际化库大小**：在捆绑、树抖动和最小化后，i18n 库的大小是提供程序（例如 `NextIntlClientProvider`）+ 钩子（例如 `useTranslations`）在空组件中的代码大小。它不包括加载翻译文件。它回答了在内容进入之前库的成本是多少。
+
+- **每页 JavaScript**：对于每个基准路由，浏览器在该访问期间拉取多少脚本，在套件中的页面上取平均值（以及在报告汇总的地方跨地区）。页面越重，页面越慢。
+
+- **来自其他地区的泄漏**：这是同一页面但用另一种语言编写的内容，会被错误地加载到审计页面中。此内容是不必要的，应该避免。（例如，`/en/about` 页面包中的 `/fr/about` 页面内容）
+
+- **来自其他路由的泄漏**：对于应用中的**其他屏幕**有相同的想法：当你只打开一个页面时，它们的副本是否会随之传输。（例如，`/en/contact` 页面包中的 `/en/about` 页面内容）。高分提示弱分割或过宽的包。
+
+- **平均组件捆绑大小**：常见 UI 片段被**一次测量一个**而不是隐藏在一个巨大的应用编号中。它展示了国际化是否悄悄地膨胀日常组件。例如，如果你的组件重新渲染，它将从内存中加载所有该数据。将一个巨大的 JSON 附加到任何组件就像连接一个大的未使用数据存储，这会减慢你的组件性能。
+
+- **语言切换响应速度**：我使用应用自己的控件来切换语言，并计时直到页面明确切换需要多长时间，这是访问者会注意到的，而不是实验室微步。
+
+- **语言更改后的渲染工作**：一个更窄的后续问题：一旦切换进行中，界面为新语言重绘需要多少工作量。当"感觉"时间和框架成本不同时很有用。
+
+- **初始页面加载时间**：从导航到浏览器认为页面完全加载的时间，用于我测试的场景。很好用于比较冷启动。
+
+- **水合时间**：当应用公开时，客户端将服务器 HTML 转换为可以实际点击的内容所花费的时间。表中的破折号意味着该实现在此基准中没有提供可靠的水合数据。
+
 ## GitHub 星数
 
 GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力指标。虽然星数不是技术质量的直接衡量标准，但它们反映了有多少开发人员发现该项目有用、关注其进展并可能采用它。在评估项目价值时，星数有助于比较不同方案的吸引力，并提供对生态系统增长的见解。

package/docs/zh/cli/ci.md

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## 脚手架 GitHub Actions
+
+当你运行 `intlayer init` 时，Intlayer 会检测你的包管理器（npm、yarn、pnpm 或 bun），并在 `.github/workflows/` 下脚手架生成两个 GitHub Actions 工作流，命令与该包管理器相匹配：
+
+- **`intlayer-fill.yml`** — 在每个 pull request 上，构建字典并运行 `intlayer fill --git-diff --mode complete` 来为更改的字典生成缺失的翻译，然后将结果提交回 PR 分支。
+- **`intlayer-test.yml`** — 在每个 pull request 上，构建字典并运行 `intlayer test`，当必需的语言环境缺少翻译时，检查失败。
+
+现有的工作流文件永远不会被覆盖。要完全跳过脚手架，运行：
+
+```bash
+npx intlayer init --no-github-actions
+```
+
+### 为 fill workflow 提供 AI 访问权限
+
+生成的 `intlayer-fill.yml` 需要 AI 访问权限。有两个选项可用（在 workflow 的 `env` 块中配置）：
+
+1. **您自己的 AI 提供商密钥** — 在您的存储库设置中添加 `AI_API_KEY` 密钥（Settings → Secrets and variables → Actions）。workflow 通过 `--provider`、`--model` 和 `--api-key` 转发它。
+2. **Intlayer CMS 访问密钥** — 添加 `INTLAYER_CLIENT_ID` 和 `INTLAYER_CLIENT_SECRET` 密钥，并将它们连接到您的 `intlayer.config` `editor` 部分。CMS 访问密钥通过 Intlayer 后端授予 AI 访问权限。
+
+`intlayer-test.yml` workflow 不需要任何 AI 访问权限。
+
 ## 错误处理
 
 - 如果未设置 `INTLAYER_PROJECT_CREDENTIALS`，命令将以错误退出。