@intlayer/docs 9.3.3 → 9.4.0

package/docs/vi/packages/react-intlayer/useIntlayer.md

@@ -31,48 +31,6 @@ Hook `useIntlayer` cho phép bạn truy xuất nội dung được bản địa
 
 ## Ví dụ sử dụng trong React
 
-Minh họa hook `useIntlayer` trong một component React:
-
-```tsx fileName="src/app.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { ClientComponentExample, ServerComponentExample } from "@components";
-import { IntlayerProvider } from "react-intlayer";
-import { useIntlayer, IntlayerServerProvider } from "react-intlayer/server";
-import { Locales } from "intlayer";
-
-const App: FC<{ locale: Locales }> = ({ locale }) => {
-  const content = useIntlayer("homepage", locale);
-
-  return (
-    <>
-      <p>{content.introduction}</p>
-      <IntlayerProvider locale={locale}>
-        <ClientComponentExample />
-      </IntlayerProvider>
-      <IntlayerServerProvider locale={locale}>
-        <ServerComponentExample />
-      </IntlayerServerProvider>
-    </>
-  );
-};
-```
-
-```tsx fileName="src/components/ComponentExample.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const ComponentExample: FC = () => {
-  const content = useIntlayer("component-example");
-
-  return (
-    <div>
-      <h1>{content.title}</h1>
-      <p>{content.description}</p>
-    </div>
-  );
-};
-```
-
 ```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat={["typescript", "esm"]}
 import { useIntlayer } from "react-intlayer/server";
 

package/docs/vi/packages/vite-intlayer/intlayerMinify.md

@@ -56,7 +56,7 @@ export default defineConfig({
 2. Tùy chọn `build.optimize` là `true` (hoặc `undefined`, mặc định sẽ là `true` đối với tiến trình build).
 3. Tùy chọn `build.minify` được đặt là `true` trong cấu hình Intlayer của bạn.
 
-Nó tự động bị **vô hiệu hóa** khi `editor.enabled` là `true` vì editor cần nội dung từ điển đầy đủ và thân thiện với người đọc.
+Khi `editor.enabled` là `true`, plugin vẫn chạy nhưng **bỏ qua bước đổi tên trường**: việc đổi tên viết lại các khóa nội dung mà trình thông dịch duyệt qua, khiến `keyPath` mà trình soạn thảo trực quan nhận được sẽ không còn khớp với các từ điển chưa hợp nhất mà nó đang chỉnh sửa. Việc nén khoảng trắng và loại bỏ metadata cấp cao nhất vẫn được giữ nguyên.
 
 ## Những gì được nén
 

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

@@ -28,6 +28,8 @@ author: aymericzip
 
 Plugin Vite `intlayerPrune` được sử dụng để thực hiện tree-shaking và loại bỏ các từ điển không được sử dụng khỏi bundle ứng dụng của bạn. Điều này giúp giảm kích thước bundle cuối cùng bằng cách chỉ bao gồm nội dung đa ngôn ngữ cần thiết.
 
+> Plugin đã được bao gồm và cấu hình tự động khi bạn sử dụng [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/vite-intlayer/intlayer.md). Bạn chỉ cần đăng ký nó theo cách thủ công nếu bạn đang soạn plugin stack của riêng mình.
+
 ## Cách sử dụng
 
 ### Như một phần của `intlayer()` (được khuyến nghị)
@@ -115,4 +117,4 @@ Khi pruning thành công, `intlayerPrune` cũng ghi `pruneContext.dictionaryKeyT
 2. `build.optimize` là `true` (hoặc `undefined`, mặc định là `true` cho các bản build).
 3. `build.purge` là `true` trong cấu hình Intlayer của bạn.
 
-Nó được tự động **vô hiệu hóa** khi `editor.enabled` là `true` vì trình chỉnh sửa cần toàn bộ nội dung từ điển.
+Nó vẫn hoạt động khi `editor.enabled` là `true`: trình soạn thảo trực quan phân giải mỗi chỉnh sửa thông qua `dictionaryKey` + `keyPath` dựa trên các từ điển chưa hợp nhất, mà plugin này không bao giờ đụng đến, và một trường đã bị loại bỏ là trường mà không component nào đọc — vì vậy nó không bao giờ được render và cũng không thể chọn được trên trang.

package/docs/vi/per_locale_file.md

@@ -77,6 +77,17 @@ const helloWorldContent = {
 module.exports = helloWorldContent;
 ```
 
+```json5 fileName="hello-world.vi.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "hello-world",
+  "locale": "vi", // Quan trọng
+  "content": {
+    "multilingualContent": "Tiêu đề của thành phần của tôi",
+  },
+}
+```
+
 ```json fileName="hello-world.content.ts" contentDeclarationFormat="json"
 {
   "$schema": "https://intlayer.org/schema.json",
@@ -95,6 +106,8 @@ module.exports = helloWorldContent;
 
 > Khuyến nghị: Định dạng này là tốt nhất khi sử dụng trình chỉnh sửa trực quan của Intlayer hoặc quản lý bản dịch trực tiếp trong mã.
 
+> Lưu ý: Trong cả hai trường hợp, tệp khai báo nội dung phải tuân theo mẫu đặt tên `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` để được Intlayer nhận diện. Hậu tố `.[locale]` là tùy chọn và chỉ được sử dụng như một quy ước đặt tên.
+
 ### Cấu hình toàn cầu cho các tệp theo từng Locale
 
 Bạn có thể cấu hình cấu hình toàn cầu cho các tệp theo từng locale bằng cách thêm nội dung sau vào tệp `intlayer.config.ts` của bạn:
@@ -146,17 +159,6 @@ const helloWorldContent = {
 export default helloWorldContent;
 ```
 
-```json5 fileName="hello-world.en.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "hello-world",
-  "locale": "en", // Quan trọng
-  "content": {
-    "multilingualContent": "Tiêu đề của thành phần của tôi",
-  },
-}
-```
-
 ```json5 fileName="hello-world.es.content.json" contentDeclarationFormat="json"
 {
   "$schema": "https://intlayer.org/schema.json",
@@ -170,8 +172,6 @@ export default helloWorldContent;
 
 > Quan trọng: Hãy chắc chắn rằng trường locale được định nghĩa. Nó cho Intlayer biết ngôn ngữ mà file đại diện.
 
-> Lưu ý: Trong cả hai trường hợp, file khai báo nội dung phải tuân theo mẫu đặt tên `*.content.{ts,tsx,js,jsx,mjs,cjs,json}` để được Intlayer nhận diện. Phần hậu tố `.[locale]` là tùy chọn và chỉ được sử dụng như một quy ước đặt tên.
-
 ## Kết hợp các định dạng
 
 Bạn có thể kết hợp cả hai cách khai báo cho cùng một khóa nội dung. Ví dụ:

package/docs/vi/readme.md

@@ -225,8 +225,8 @@ Khám phá tài liệu toàn diện của chúng tôi để bắt đầu với I
   <li><a href="https://intlayer.org/doc/environment/vite-and-vue" rel=''>Vite + Vue</a></li>
   <li><a href="https://intlayer.org/doc/environment/nuxt-and-vue" rel=''>Vite + Nuxt</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-solid" rel=''>Vite + Solid</a></li>
-  <li><a href="https://intlayer.org/doc/environment/angular" rel=''>Angular</a></li>
-  <li>
+  <li><a href="https://intlayer.org/doc/environment/solid-start" rel=''>Solid Start</a></li>
+  <li><a href="https://intlayer.org/doc/environment/angular" rel=''>Angular</a></li>  <li>
      <a href="https://intlayer.org/doc/environment/express" rel=''>Backend</a>
      <ul>
       <li><a href="https://intlayer.org/doc/environment/express" rel=''>Express</a></li>
@@ -234,6 +234,7 @@ Khám phá tài liệu toàn diện của chúng tôi để bắt đầu với I
       <li><a href="https://intlayer.org/doc/environment/fastify" rel=''>Fastify</a></li>
       <li><a href="https://intlayer.org/doc/environment/adonisjs" rel=''>AdonisJS</a></li>
       <li><a href="https://intlayer.org/doc/environment/hono" rel=''>Hono</a></li>
+      <li><a href="https://intlayer.org/doc/environment/elysia" rel=''>Elysia</a></li>
     </ul>
   </li>
 </ul>

package/docs/vi/self_hosting.md

@@ -21,12 +21,16 @@ author: aymericzip
 
 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:
 
+Một lệnh cài đặt mọi thứ:
+
 ```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`.
 
+Sự phụ thuộc duy nhất bên ngoài là **MongoDB**: backend kết nối với một cluster **Atlas** MongoDB mà bạn cung cấp. Mọi thứ khác chạy bên trong container.
+
 ## Mục lục
 
 <TOC/>
@@ -60,40 +64,82 @@ Chromium (được sử dụng để tạo ảnh chụp màn hình Puppeteer) đ
 - 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).
 
+Mọi thứ khác — Bun, Redis, MinIO, Chromium — đều được đóng gói trong image.
+
 ---
 
 ## Bắt đầu nhanh
 
-Pull và chạy image được công bố, cung cấp thông tin xác thực và bí mật MongoDB Atlas của bạn:
+### 1. Chạy trình cài đặt
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+Nó xác minh Docker đã được cài đặt và đang chạy, ghi `./intlayer.env` với `BETTER_AUTH_SECRET` và `S3_SECRET_ACCESS_KEY` đã được tạo sẵn, và kéo image. Nó không khởi động container — backend không thể khởi động mà không có thông tin đăng nhập cơ sở dữ liệu của bạn.
+
+Chạy lại trình cài đặt là an toàn: một `intlayer.env` hiện có sẽ không bao giờ bị ghi đè, vì vậy nó cũng đóng vai trò là đường dâng cập nhật.
+
+### 2. Điền thông tin đăng nhập của bạn
+
+Mở `intlayer.env` và hoàn thành các giá trị được đánh dấu `TODO`:
+
+```sh fileName="intlayer.env"
+DB_ID=<atlas-user>
+DB_MDP=<atlas-password>
+DB_CLUSTER=<cluster>.xxxxx.mongodb.net
+RESEND_API_KEY=<your-resend-key>
+```
+
+Tệp này cũng chứa các khối được comment cho các tính năng tùy chọn — [SMTP mailer](#global-mailer), `OPENAI_API_KEY`, và các nhà cung cấp OAuth. Bỏ comment những tính năng bạn cần.
+
+> Tệp được đọc bởi `docker run --env-file`, tệp này không loại bỏ dấu ngoặc kép và xem mọi thứ sau `=` là giá trị. Viết các giá trị không có dấu ngoặc kép, và giữ các comment trên các dòng riêng biệt.
+
+### 3. Khởi động container
+
+Đây là lệnh mà trình cài đặt in ra khi hoàn thành:
 
 ```sh
 docker run -d --name intlayer \
+  --restart unless-stopped \
   -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
+  --env-file ./intlayer.env \
+  ghcr.io/aymericzip/intlayer-selfhost:latest
 ```
 
-Sau đó mở **http://localhost:3000**.
+Sau đó mở **http://localhost:3000**. Lần khởi động đầu tiên sẽ khởi tạo các datastores, vì vậy hãy chờ một phút.
 
-> Dashboard được phục vụ trên `localhost`. Xem [Limitations](#limitations) — các miền tùy chỉnh không được hỗ trợ bởi image được công bố.
+> Dashboard được phục vụ trên `localhost`. Xem [Limitations](#limitations) — các custom domains không được hỗ trợ bởi image được công bố.
 
----
+### Cài đặt Installer
 
-## Bắt đầu nhanh
+Installer đọc một số biến môi trường. Vì nó được pipe vào `sh`, hãy truyền chúng cho shell thay vì cho `curl`:
 
 ```sh
-curl -fsSL https://intlayer.org/install.sh | sh
+curl -fsSL https://intlayer.org/install.sh | INTLAYER_ENV_FILE=./config/intlayer.env sh
 ```
 
+| Variable                  | Default                                       | Description                      |
+| ------------------------- | --------------------------------------------- | -------------------------------- |
+| `INTLAYER_IMAGE`          | `ghcr.io/aymericzip/intlayer-selfhost:latest` | Image để pull                    |
+| `INTLAYER_ENV_FILE`       | `./intlayer.env`                              | Nơi ghi file env                 |
+| `INTLAYER_CONTAINER_NAME` | `intlayer`                                    | Tên container                    |
+| `INTLAYER_DATA_VOLUME`    | `intlayer-data`                               | Named volume mounted tại `/data` |
+| `INTLAYER_APP_PORT`       | `3000`                                        | Host port cho dashboard          |
+| `INTLAYER_API_PORT`       | `3100`                                        | Host port cho API                |
+| `INTLAYER_S3_PORT`        | `9000`                                        | Host port cho MinIO S3 API       |
+| `INTLAYER_CONSOLE_PORT`   | `9001`                                        | Host port cho MinIO console      |
+
+> Bốn biến port chỉ thay đổi phía **host** của mapping được in trong lệnh `docker run`. Image được công bố có `http://localhost:3000`, `http://localhost:3100` và `http://localhost:9000` được biên dịch vào dashboard bundle tại thời điểm build, vì vậy việc ánh xạ lại chúng làm cho trình duyệt chỉ đến các port cũ. Giữ các giá trị mặc định trừ khi bạn đang xây dựng image của riêng mình — xem [Limitations](#limitations).
+
+---
+
+## Bắt đầu nhanh
+
 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.
@@ -117,8 +163,6 @@ Sau khi stack hoạt động, mở **http://localhost:3000** và tạo tài kho
 | **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`.
 
 ---
@@ -174,8 +218,6 @@ Các cổng nội bộ (mongo, redis) không được phơi bày ra host theo m
 | `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`           | Đăng nhập LinkedIn OAuth                                       |
 | `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`         | Đăng nhập Atlassian OAuth                                      |
 
----
-
 ### Mailer toàn cầu
 
 Theo mặc định, tất cả các email giao dịch được gửi qua Resend sử dụng `RESEND_API_KEY`. Các triển khai tự lưu trữ có thể thay vào đó định tuyến **mọi** email — bao gồm các email không thuộc tổ chức như đặt lại mật khẩu và liên kết ma thuật — qua một mailer toàn cầu được định cấu hình bằng các biến môi trường.
@@ -261,16 +303,8 @@ 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
@@ -334,15 +368,12 @@ docker compose logs mongo
 docker compose logs redis
 ```
 
+Tìm kiếm `MongoDB connection error` gần phía trên của log.
+
 ### 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
-```
-
 ### 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:

package/docs/zh/agent_skills.md

@@ -1,11 +1,11 @@
 ---
 createdAt: 2026-02-09
 updatedAt: 2026-03-03
-title: 代理技能
-description: 了解如何使用 Intlayer 代理技能来提高 AI 代理对项目的理解，包括元数据 (Metadata)、站点地图 (Sitemaps) 和服务器操作 (Server Actions) 的全面设置指南。
+title: Agent Skills
+description: 了解如何使用 Intlayer Agent Skills 来提高 AI 代理对项目的理解，包括元数据 (Metadata)、站点地图 (Sitemaps) 和服务器操作 (Server Actions) 的全面设置指南。
 keywords:
   - Intlayer
-  - 代理技能
+  - Agent Skills
   - AI 代理
   - 国际化
   - 文档
@@ -19,13 +19,13 @@ history:
 author: aymericzip
 ---
 
-# 代理技能
+# Agent Skills
 
 ## 设置
 
 ### 使用 CLI
 
-`intlayer init skills` 命令是在项目中设置代理技能的最简单方法。它会检测您的环境并为您喜欢的平台安装必要的配置文件。
+`intlayer init skills` 命令是在项目中设置 Agent Skills 的最简单方法。它会检测您的环境并为您喜欢的平台安装必要的配置文件。
 
 ```bash packageManager="npm"
 npx intlayer init skills
@@ -54,10 +54,10 @@ npx skills add aymericzip/intlayer-skills
 1. 打开命令面板 (Ctrl+Shift+P 或 Cmd+Shift+P)。
 2. 输入 `Intlayer: Setup AI Agent Skills`
 3. 选择您使用的平台（例如 `VS Code`、`Cursor`、`Windsurf`、`OpenCode`、`Claude Code`、`GitHub Copilot Workspace` 等）。
-4. 选择您要安装的技能（例如 `Next.js`、`React`、`Vite`、`Compiler`、`Configuration`）。
+4. 选择您要安装的 Agent Skills（例如 `Next.js`、`React`、`Vite`、`Compiler`、`Configuration`）。
 5. 按 Enter 键。
 
-## 技能列表
+## Agent Skills 列表
 
 **intlayer-config**
 

package/docs/zh/analytics.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-07-08
-updatedAt: 2026-07-08
+updatedAt: 2026-08-22
 title: Intlayer Analytics | 跟踪内容曝光并运行 A/B 测试
 description: 探索 @intlayer/analytics 如何跟踪页面/区域设置浏览量和内容曝光，以及如何使用它对您的 Intlayer 内容运行 A/B 测试。
 keywords:
@@ -18,6 +18,9 @@ slugs:
   - concept
   - analytics
 history:
+  - version: 9.3.3
+    date: 2026-08-22
+    changes: "安装 `@intlayer/analytics` 后默认启用分析功能"
   - version: 9.0.0
     date: 2026-07-08
     changes: "Init doc — @intlayer/analytics 包，Provider/Node级别跟踪，A/B 测试，仪表板"
@@ -57,7 +60,7 @@ Intlayer 已经允许您声明内容 [变体 (Variants)](https://github.com/ayme
 
 ## 安装
 
-`@intlayer/analytics` 是一个**对等 (peer)、可选**的依赖项 —— 框架包永远不会自动安装它。请将其与 `intlayer` 一起添加：
+`@intlayer/analytics` 是每个框架包（`react-intlayer`、`next-intlayer`、`vue-intlayer` 等）的**可选依赖（optional dependency）**，因此大多数项目已经安装了它。如果你的安装流程跳过可选依赖（例如 `npm install --no-optional`），请显式安装：
 
 ```bash packageManager="npm"
 npm install @intlayer/analytics
@@ -75,11 +78,11 @@ pnpm add @intlayer/analytics
 bun add @intlayer/analytics
 ```
 
-如果您不安装它，每个集成点都将解析为空操作 (no-op) —— 请参阅下文的[未安装时零成本](#未安装时零成本)。
+只需安装该包即可启用分析功能：`analytics.enabled` 默认为 `true`，当在你的项目中找不到该包时，`@intlayer/config` 会将其解析为 `false`。如果您不安装它，每个集成点都将解析为空操作 (no-op) —— 请参阅下文的[未安装时零成本](#未安装时零成本)。
 
 ## 配置
 
-Analytics **重用了现有的 `editor` 配置块** —— 没有单独的 `analytics` 配置模式需要填写：
+分析功能无需任何配置即可启动：它**默认启用**，并**复用现有的 `editor` 配置块**作为其上报地址和项目密钥。
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
 import type { IntlayerConfig } from "intlayer";
@@ -100,16 +103,25 @@ export default config;
 
 如果您自托管 Intlayer，分析会自动指向您自己的实例，因为它共享 `editor.backendURL`。
 
-## 框架支持
+### 如何关闭
 
-Analytics 已连接到 `react-intlayer` 共享的 `IntlayerProvider` 中，因此今天只要使用该 provider 的任何地方都可以使用它：
+可选的 `analytics` 配置块用于调整——或关闭——数据收集：
 
-| 框架                                                     | 状态                                                                       |
-| -------------------------------------------------------- | -------------------------------------------------------------------------- |
-| React                                                    | ✅ 可用                                                                    |
-| Next.js (`next-intlayer`)                                | ✅ 可用 (通过 `react-intlayer`)                                            |
-| React Native / Expo (`react-native-intlayer`)            | ✅ 可用 (通过 `react-intlayer`)                                            |
-| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 计划中 — 相同的客户端，遵循 `@intlayer/editor` 推出模式的提供商级别绑定 |
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  analytics: {
+    enabled: false, // 默认值：true —— 将整个集成排除在打包结果之外
+    flushInterval: 20_000, // 两次批量发送之间的毫秒数
+    sampleRate: 1, // 要记录的会话比例，从 0（不记录）到 1（全部记录）
+  },
+};
+
+export default config;
+```
+
+卸载 `@intlayer/analytics` 与设置 `enabled: false` 效果相同。完整字段列表请参阅[配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
 ## 使用方法
 
@@ -154,6 +166,34 @@ const CTAButton = () => {
 
 ### 在客户端解析变体
 
+  </Tab>
+</Tabs>
+
+权重是可选的 — 为每个变体传递一个权重来改变分割比例，例如 `useExperiment("homepage-hero", ["default", "black_friday"], [9, 1])`。
+
+子应用随后读取与之匹配的字典的 [Variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/variants.md)：
+
+```tsx fileName="HeroBanner.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const HeroBanner = ({ variant }: { variant: string }) => {
+  const { headline, cta } = useIntlayer("hero-banner", { variant });
+
+  return (
+    <section>
+      <h1>{headline}</h1>
+      <a>{cta}</a>
+    </section>
+  );
+};
+```
+
+> 在**子组件**中读取 variant 是使其在 React 之外工作的关键：在 Vue、Svelte、Solid 和 Angular 中，传递给 `useIntlayer` 的选择器在组件设置时被捕获，所以读取必须发生在仅在 variant 已知时才挂载的组件中。
+
+如果实验涵盖整个页面而不是单个字典，请将变体提升到提供者上——参见 [Ambient variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/variants.md#ambient-variant)。下面的每个 `useIntlayer` 都会针对它进行解析，无需更改调用站点。
+
+如果你需要在组件外部获取原始赋值，直接访问客户端：
+
 ```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
 import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
 
@@ -164,6 +204,8 @@ const variant = client?.getVariant("homepage-hero", [
 ]);
 ```
 
+> `getVariant` 只进行分配——它不记录曝光。优先使用 `useExperiment()`，否则转化率将没有分母。
+
 ## 隐私与性能
 
 - **设计上匿名**：会话由轮换 ID 标识；后端永远只存储该 ID 的 **SHA-256 哈希值** —— 从不存储原始 ID，从不存储 IP 地址。
@@ -177,7 +219,7 @@ const variant = client?.getVariant("homepage-hero", [
 `@intlayer/analytics` 遵循与 `@intlayer/editor` 完全相同的可选依赖模式：
 
 - 每个集成点通过**包裹在 `try/catch` 中的动态 `import()`** 加载包 —— 从未安装 `@intlayer/analytics` 的应用程序永远不会支付包大小或运行时成本，也永远不会看到错误；
-- 一个编译时环境变量（`INTLAYER_ANALYTICS_ENABLED`），当没有配置 `editor.clientId` 时，它会由 `@intlayer/config` 自动设置为 `'false'`，允许打包器 (bundlers) **将整个集成作为死代码消除 (dead-code-eliminate)**；
+- 一个编译时环境变量（`INTLAYER_ANALYTICS_ENABLED`），当该包未安装、`analytics.enabled` 为 `false`，或未配置 `editor.clientId` 时，它会由 `@intlayer/config` 自动设置为 `'false'`，允许打包器 (bundlers) **将整个集成作为死代码消除 (dead-code-eliminate)**；
 - 分析在 Intlayer 编辑器/CMS 预览 iframe 中被禁用，因此编辑器会话永远不会算作真实流量。
 
 ## 仪表板：Analytics 页面
@@ -213,6 +255,8 @@ const cms = createIntlayerCMS();
 const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
 ```
 
+> **仅限服务器端。** `createIntlayerCMS()` 使用 `clientId` + `clientSecret` 进行身份验证，secret 永远不会在浏览器中可用 — 如果此代码片段在浏览器中运行，它将发出未经身份验证的请求。请将其保留在路由处理程序、服务器操作或脚本中。
+
 ## 有用的链接
 
 - [动态字典 - 集合与变体 (Collections & Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dynamic_dictionaries/index.md)

package/docs/zh/benchmark/tanstack.md

@@ -196,6 +196,8 @@ GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力
 
 在 TanStack Start 上我也遇到了响应性问题：切换语言环境时，我必须强制 Provider 重新渲染并订阅语言环境更改事件，切换后的加载才能正常进行。
 
+在 TanStack Start 上，我也遇到了响应性问题：当locale改变时，我必须强制提供者重新渲染并订阅locale-change事件，以便在另一种语言中加载时行为正确。
+
 **(use-intl)** (`use-intl@4.9.1`):
 
 `use-intl` 是 React 生态中最时髦的“intl”成员（与 `next-intl` 同系），常被 AI Agent 推荐，但在我看来，在性能优先的环境下这是错误的。入门相对简单，但在实践中，优化和限制泄漏的过程相当复杂。同样，结合动态加载 + 命名空间 + TypeScript 类型会极大降低开发速度。
@@ -208,6 +210,8 @@ GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力
 
 尽管如此，它与基于 `t('a.b.c')` 的技术栈有着相同的重大缺点：优化是可能的，但非常耗时，且大型项目容易陷入不良实践（命名空间 + 动态加载 + 类型）。
 
+该 package 特别重（~17.3kb，约为 `react-intlayer` 的 3.5 倍）。
+
 消息格式也不同：`use-intl` 使用 ICU MessageFormat，而 `i18next` 使用自己的格式--如果混合使用它们，会增加工具链或迁移的复杂度。
 
 **(Lingui)** (`@lingui/core@5.3.0`):
@@ -218,6 +222,8 @@ GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力
 
 `react-intl` 是来自 Format.js 团队的高性能实现。但 DX 依然繁琐：`const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })` 增加了复杂度和额外的 JavaScript 开销，并将全局 i18n 实例绑定到了 React 树中的许多节点。
 
+该 package 也很重（~14.4kb，大约是 `react-intlayer` 的 3 倍）。
+
 ### 4 - 推荐方案
 
 在本次 TanStack Start 基准测试中，没有与 `next-translate`（Next.js 插件 + `getStaticProps`）直接对应的方案。对于那些确实想要 `t()` API 且拥有成熟生态的团队，`react-i18next` 和 `use-intl` 仍是“合理”的选择，但要做好投入大量时间进行优化以避免泄漏的准备。

package/docs/zh/bundle_optimization.md

@@ -476,7 +476,7 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> 如果在 `optimize` 被设为 `false`、又或是启用了可视化编辑器也就是当 `editor.enabled` 设定为了 `true` 时（由于编辑器需要保留字段名称以便做后续处理），重命名这个操作都将会被跳过。
+> 当 `optimize` 为 `false` 时，压缩会被跳过。当 `editor.enabled` 为 `true` 时，压缩仍会运行，但不执行字段重命名步骤——可视化编辑器通过 `keyPath` 解析编辑内容，因此原始字段名称必须保留。
 
 > 在 Next.js 上，当 `@intlayer/swc` 未安装或无法加载时（Next.js 低于 16.1.0），压缩同样会被跳过。重写源码访问的正是这个插件，因此在没有它的情况下重命名字典，会让你的代码读取已不存在的字段名。
 
@@ -508,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> 与前边提到的类似，当 `optimize` 是 `false` 或是开启了可视化编辑器(`editor.enabled` 取值 `true`) 时，它会选择跳过对数据的清除操作。 在 Next.js 上，当 `@intlayer/swc` 不可用以及配置了兼容适配器调用方时，还会被额外跳过。
+> 当 `optimize` 为 `false` 时，清除（Purge）会被跳过。当 `editor.enabled` 为 `true` 时，它仍保持启用——被清除的字段不会被任何组件读取，因此编辑器永远不会渲染它。在 Next.js 上，当 `@intlayer/swc` 不可用以及配置了兼容适配器调用方时，还会被额外跳过。
 
 > 当检测到某份代码因为异常无法顺利解析、又或者当把由 `useIntlayer` 输出的值以静态解析器难以预测分析的模式在不同组件中来回丢（比如被打包成对象传入等而未被进行解构）的时候，它同样会跳过，以此保守地保留整部字典的全部信息，避免意外发生。
 

package/docs/zh/cli/ci.md

@@ -128,6 +128,8 @@ bun x intlayer ci fill --verbose --mode complete
 
 ### 在 CI/CD 管道中使用
 
+运行 `intlayer init` 为你生成两个可立即使用的 GitHub Actions 工作流（参见下面的 [Scaffolded GitHub Actions](#scaffolded-github-actions)）。这个例子展示了在 monorepo 中使用 `ci` 命令的等效设置，其中凭证从 `INTLAYER_PROJECT_CREDENTIALS` 按项目注入。
+
 在您的 CI/CD 配置中（例如，GitHub Actions、GitLab CI），将 `INTLAYER_PROJECT_CREDENTIALS` 设置为密钥：
 
 ```yaml

package/docs/zh/cli/doc-review.md

@@ -91,7 +91,13 @@ bun x intlayer doc review
 
 - **`--log`**：仅记录模式。不使用 AI 进行翻译；而是记录需要关注的块（带有行号和内容），供基础语言环境和目标语言环境参考，以帮助另一个代理生成翻译。
 
-  > 示例：`npx intlayer doc review --log`
+2. **For `report` mode**: Log blocks requiring attention without using AI, noting line numbers and content for both source and target.
+
+> 示例: `npx intlayer doc review --mode report`
+
+> 示例：`npx intlayer doc review --log`
+
+无论采用哪种模式，运行都会以一份综合报告结束，该报告列出与其基础文档对齐的文档和仍有需要编辑的块的文档。
 
 **入口输出选项：**
 

package/docs/zh/cli/fill.md

@@ -39,14 +39,6 @@ bun x intlayer fill
 
 此命令会分析您的内容声明文件，查找潜在问题，例如缺失的翻译、结构不一致或类型不匹配。如果发现任何问题，**intlayer fill** 将建议或应用更新，以保持您的字典一致且完整。
 
-关键要点：
-
-- 将大型 JSON 文件拆分为块，以保持在 AI 模型的上下文窗口限制内。
-- 如果输出格式不正确，会重试翻译。
-- 结合应用程序和文件特定的上下文以提高翻译准确性。
-- 通过不覆盖现有翻译来保留它们。
-- 使用队列系统并行处理文件、块和语言环境以提高速度。
-
 ## 关键要点：
 
 - 将大型 JSON 文件分割成块，以保持在 AI 模型的上下文窗口限制内。

package/docs/zh/cli/index.md

@@ -127,6 +127,8 @@ Intlayer 接受多种配置文件格式：
 
 - **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/login.md)** - 在 Intlayer CMS 中进行身份验证并获取访问凭据
 
+> `intlayer login` 生成一个**访问密钥** (`clientId` / `clientSecret`)，每个需要凭证的命令都会使用它。该密钥是服务器端凭证，永远不会到达您的客户端 bundle — 请参阅[保持访问密钥安全](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/login.md#keeping-the-access-key-safe)。
+
 ### 核心命令
 
 - **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/build.md)** - 从内容声明文件构建字典

package/docs/zh/cli/list_projects.md

@@ -52,8 +52,6 @@ bun x intlayer projects list
 
   > 示例：`npx intlayer projects list --base-dir /path/to/workspace`
 
-  > 示例：`npx intlayer projects list --base-dir /path/to/workspace`
-
 - **`--git-root`**：从 git 根目录开始搜索，而不是基目录。这对于在 monorepo 或 git 仓库中查找所有 Intlayer 项目很有用。
 
   > 示例：`npx intlayer projects list --git-root`

package/docs/zh/cli/login.md

@@ -118,6 +118,34 @@ INTLAYER_CLIENT_SECRET=your_client_secret
 }
 ```
 
+## 保持访问密钥安全
+
+`intlayer login` 颁发一个**访问密钥**：一个 `clientId` / `clientSecret` 对，每个需要凭证的命令（`push`、`pull`、`fill`、`configuration push`、`live` 等）都使用它来进行身份验证。
+
+```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,
+  },
+};
+
+export default config;
+```
+
+> **`clientSecret` 是一个服务器端凭证。** 它授予完整的项目范围 API 访问权限——读取和写入您的字典、项目和组织。将其保存在 `.env`（被 git 忽略）或您的 CI 密钥存储中，切勿在配置文件中直接内联。
+
+Intlayer 强制执行此操作，而不仅仅是记录它：
+
+- `clientSecret` **从您的 bundler 内联的配置中被删除**，因此无论您使用何种框架集成，它都无法到达浏览器包。它仅在服务器端、运行时从环境中读取。
+- `clientId` 不同：它是**公开的**项目密钥，可以安全地交付，并由 [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/analytics.md#how-events-are-authenticated) 使用以获取短期的、仅供摄取的 token。
+
+注释掉 `clientId` 足以禁用每个需要凭证的行为——远程字典获取、CMS 访问、分析——即使环境变量仍然已定义。
+
+对于 CI 管道，推荐使用 [`ci` 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/ci.md)，它在单次运行期间注入凭证，而不是持久化它们。
+
 ## 手动配置
 
 如果浏览器没有自动打开，您可以手动访问终端中显示的 URL。