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

package/docs/vi/releases/v9.md

@@ -0,0 +1,316 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-26
+title: Intlayer v9 Mới - Có gì mới?
+description: Khám phá các tính năng mới trong Intlayer v9. Giới thiệu các package tương thích drop-in cho các thư viện i18n phổ biến và hỗ trợ Collections và Variants.
+keywords:
+  - Intlayer
+  - Compatibility
+  - Migration
+  - Collections
+  - Variants
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# Intlayer v9 Mới - Có gì mới?
+
+Chào mừng bạn đến với Intlayer v9! Bản phát hành lớn này đánh dấu một cột mốc quan trọng trong việc đơn giản hóa lộ trình migration sang Intlayer với các **Compat Adapter Packages** dành cho các thư viện i18n phổ biến (`react-i18next`, `next-intl`, `vue-i18n`, v.v.) và bổ sung hỗ trợ cho các cấu trúc nội dung phong phú: **Collections** và **Variants**.
+
+## Mục lục
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat Adapter Packages
+
+Việc migration sang Intlayer từ các thư viện i18n phổ biến giờ đây dễ dàng hơn bao giờ hết. Chúng tôi đã tạo ra năm compat package cung cấp **chính xác các public API tương tự** như các thư viện i18n tiêu chuẩn nhưng ủy quyền toàn bộ việc xử lý translation cho Intlayer tại runtime.
+
+### Cung cấp cùng một Public API với Strict Typing
+
+Bằng cách thay thế các import, bạn sẽ nhận được tất cả các lợi ích của Intlayer (bao gồm cả compile-time type safety dựa trên các dictionary thực tế của bạn) với những thay đổi code tối thiểu:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/react-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+- `@intlayer/lingui`
+
+Ví dụ, chỉ cần thay đổi:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+thành:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Các key của bạn giờ đây sẽ được **strictly typed** dựa trên các Intlayer dictionary của bạn, mang lại khả năng auto-completion dot-path đầy đủ trong IDE của bạn!
+
+### Bundler Alias Plugins (Vite, Next.js, Turbopack)
+
+Để cho phép migration mà không cần phải viết lại tất cả các câu lệnh import một cách thủ công, mỗi compat adapter package đều đi kèm một **custom bundler plugin** (Vite hoặc Next.js) dưới subpath `/plugin`.
+
+Các plugin này tự động rewrite các import hiện có (ví dụ: `react-i18next` hoặc `next-intl`) thành các package tương đương `@intlayer/*` tại build time.
+
+#### Ví dụ Next.js (Webpack / Turbopack)
+
+Thay vì `withIntlayer`, hãy bọc cấu hình Next.js của bạn bằng compat plugin:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Ví dụ Vite (React, Vue, Solid, Svelte)
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Mutualized Runtime Resolver
+
+Tất cả các compat adapter giờ đây đều định tuyến việc xử lý translation thông qua một runtime parser duy nhất và được tối ưu hóa cao: `@intlayer/core/messageFormat`.
+
+- **Interpolate Message**: Xử lý các cú pháp tiêu chuẩn `{{var}}` (whitespace & dot-paths), các đối số định dạng ICU (`{v, number, percent}` v.v.), và các template `{var}` cơ bản.
+- **Message Node Resolver**: Xử lý các node lồng nhau: `insert()`, `plural()` (quy tắc số nhiều CLDR), `enu()` (enumeration), `gender()`, các thẻ HTML, array, và các callable function node.
+- **Tokenized Tag Parser**: Hỗ trợ các thẻ XML/HTML inline và các thẻ được đánh số (ví dụ: `<1>children</1>`) để hỗ trợ render rich-text một cách dễ dàng.
+
+---
+
+## Chi tiết tính năng: Collections & Variants
+
+Intlayer v9 mở rộng vượt ra ngoài các đối tượng key-value tĩnh, cho phép các dictionary khai báo các cấu trúc layout động được định kiểu đầy đủ (fully typed) từ đầu đến cuối.
+
+### 1. Collections
+
+Định nghĩa một danh sách các item có thứ tự do CMS quản lý (ví dụ: FAQ, sản phẩm, hoặc danh sách blog):
+
+```ts fileName="faq.1.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+```
+
+```ts fileName="faq.2.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
+} satisfies Dictionary;
+```
+
+#### Cách sử dụng:
+
+```ts
+// Fetch all items as an array
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Fetch a single item by index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
+```
+
+### 2. Variants
+
+Cung cấp các bản thử nghiệm A/B, seasonal header, feature flag, hoặc các landing page tùy chỉnh:
+
+#### Các biến thể chuỗi (ví dụ: thử nghiệm A/B)
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ vi: "Chào mừng", en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({
+      vi: "Mua ngay",
+      en: "Shop now",
+      fr: "Acheter maintenant",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+#### Cách sử dụng:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+#### Các biến thể đối tượng (ví dụ: Dynamic Records)
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  variant: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ vi: "Clean Code", en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Cách sử dụng:
+
+```ts
+// Chỉ tải động item được yêu cầu (yêu cầu Suspense)
+const product = useIntlayer("product-copy", {
+  variant: { id: "prod_123", category: "books" },
+});
+```
+
+---
+
+## Tối ưu hóa Dynamic Loading & Bundle Size
+
+Để giữ cho các bundle cực kỳ nhỏ gọn, Intlayer v9 hỗ trợ dynamic lazy loading.
+
+Trong cấu hình của bạn, hãy đặt `importMode` thành `'dynamic'` hoặc `'fetch'`:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+Tại build time, `@intlayer/swc` và `@intlayer/babel` sẽ quét các file của bạn và thay thế các lệnh gọi `useIntlayer` / `getIntlayer` bằng các wrapper có khả năng tree-shake (`useDictionary` / `useDictionaryDynamic`). Chỉ nội dung được yêu cầu cho collection item, variant, hoặc locale đã chọn mới được tải, giúp ngăn production bundle của bạn chứa các bản dịch không sử dụng.
+
+---
+
+## Vite Plugin: Bundled Compiler & Proxy
+
+Plugin Vite `intlayer()` hiện đóng gói **compiler** và **locale-routing proxy** trực tiếp, vì vậy hầu hết các dự án chỉ cần một plugin duy nhất trong `vite.config.ts`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: Kích hoạt tự động khi `compiler.enabled` được đặt thành `true` và một đường dẫn `compiler.output` được cấu hình. Bạn không còn cần phải đăng ký `intlayerCompiler()` riêng biệt.
+- **Proxy**: Kích hoạt tự động dựa trên tùy chọn `routing.enableProxy` mới (`true` theo mặc định). Nó kết nối middleware phát hiện ngôn ngữ / chuyển hướng / ghi đè trong phát triển, xem trước và SSR sản xuất. Bạn không còn cần phải đăng ký `intlayerProxy()` riêng biệt.
+
+### Tùy chọn `routing.enableProxy`
+
+Một tùy chọn `routing.enableProxy` mới kiểm soát xem proxy định tuyến locale có được cắm vào hay không. Nó mặc định là `true`. Vô hiệu hóa nó khi bạn muốn xử lý định tuyến locale của riêng mình:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // Mặc định: true
+  },
+};
+
+export default config;
+```
+
+Các plugin độc lập `intlayerCompiler()` và `intlayerProxy()` vẫn được xuất cho các cài đặt nâng cao. Đăng ký chúng cùng với `intlayer()` là an toàn — mỗi plugin loại bỏ chính nó và chỉ chạy một lần.
+
+---
+
+## Compiler bị tắt theo mặc định
+
+Kể từ Intlayer v9, **compiler bị tắt theo mặc định** (`compiler.enabled` hiện mặc định là `false`). Để bật trích xuất các file `.content.ts` của bạn tại thời điểm build, hãy đặt `compiler.enabled: true` trong cấu hình của bạn:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Mặc định: false — bắt buộc để bật compiler kể từ v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+Khi compiler bị tắt, Intlayer bỏ qua bước trích xuất tại thời điểm build và dựa vào các dictionary mà bạn đã khai báo. Chỉ bật nó khi bạn muốn plugin bundler (`@intlayer/swc`, `@intlayer/babel`, hoặc plugin Vite `intlayer()`) tự động trích xuất nội dung.
+
+---
+
+## React Native: import từ một package duy nhất
+
+Trong ứng dụng React Native hoặc Expo, bạn không còn cần phải xoay sở giữa `react-intlayer` và `react-native-intlayer` nữa. Package `react-native-intlayer` hiện **xuất lại toàn bộ API của `react-intlayer`** (các hook, tiện ích và các đường dẫn phụ `/format`, `/html`, và `/markdown`), và `IntlayerProvider` của nó tự động áp dụng các polyfill của React Native.
+
+Import mọi thứ từ package `react-native-intlayer` duy nhất:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Việc import từ `react-intlayer` vẫn tiếp tục hoạt động, nhưng `react-native-intlayer` hiện là điểm vào duy nhất được khuyên dùng cho React Native — provider của nó cung cấp các polyfill mà provider định hướng web `react-intlayer` không có.
+
+---
+
+## Lưu ý khi migration từ v8
+
+Nếu bạn đang nâng cấp từ v8, lưu ý rằng v9 không bao gồm các breaking change. Tuy nhiên, dưới đây là các thay đổi chính:
+
+- **Compiler bị tắt theo mặc định**: `compiler.enabled` hiện mặc định là `false`. Nếu bạn dựa vào việc trích xuất các file `.content.ts` tại thời điểm build, hãy đặt `compiler.enabled: true` trong `intlayer.config.ts` của bạn.
+- **Locales & Dialects**: Nếu sử dụng các dependency i18n bên ngoài, hãy thêm các compat adapter plugin tương ứng của chúng vào cấu hình hoặc thiết lập bundler của bạn để tự động rewrite các import.
+- **Custom Selectors**: Khi gọi `useIntlayer`, tham số thứ hai giờ đây được dành riêng cho một đối tượng option chứa `{ locale, item, variant }`. Nếu trước đây bạn đã truyền trực tiếp một chuỗi locale, bạn vẫn có thể làm như vậy, nhưng việc sử dụng đối tượng options được khuyến nghị cho các lựa chọn nâng cao.
+
+---
+
+## Liên kết hữu ích
+
+- [Hướng dẫn về Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/compat/index.md)
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md)
+- [Tài liệu tham khảo cấu hình](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md)

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`，命令将以错误退出。