@intlayer/docs 9.3.1 → 9.3.2

package/docs/vi/eslint.md

@@ -0,0 +1,336 @@
+---
+createdAt: 2026-08-12
+updatedAt: 2026-08-12
+title: Plugin ESLint | Quy tắc Lint cho Intlayer
+description: Phát hiện chuỗi văn bản bị hardcode, các lệnh gọi động mà trình biên dịch Intlayer không thể tối ưu hóa và nội dung từ điển không sử dụng với eslint-plugin-intlayer. Hoạt động với ESLint và oxlint trên React, Vue, Svelte, Angular và Astro.
+keywords:
+  - Intlayer
+  - ESLint
+  - oxlint
+  - Linting
+  - i18n
+  - Quốc tế hóa
+  - no-raw-text
+  - Chuỗi văn bản hardcoded
+  - Bản dịch không sử dụng
+  - Nội dung thừa
+  - React
+  - Vue
+  - Svelte
+  - Angular
+slugs:
+  - doc
+  - eslint
+history:
+  - version: 9.3.1
+    date: 2026-08-12
+    changes: "Lịch sử khởi tạo"
+author: aymericzip
+---
+
+# Plugin ESLint x OXLint
+
+`eslint-plugin-intlayer` giúp bắt các lỗi i18n mà TypeScript không thể phát hiện:
+
+1. **Văn bản hardcode** chưa từng được đưa vào từ điển.
+2. **Các lệnh gọi động** vượt qua kiểm tra kiểu và thực thi được, nhưng trình biên dịch Intlayer không thể tối ưu hóa.
+3. **Nội dung thừa (Dead content)** — các từ điển và trường không có bất kỳ phần nào trong dự án đọc (tùy chọn kích hoạt).
+
+Các khóa từ điển không xác định, đường dẫn trường không xác định và ngôn ngữ còn thiếu vốn đã là các lỗi biên dịch, vì vậy plugin sẽ không lặp lại chúng.
+
+## Cài đặt
+
+```bash packageManager="npm"
+npm install --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add --dev eslint-plugin-intlayer
+```
+
+Yêu cầu ESLint 9 trở lên (flat config).
+
+## Cách sử dụng
+
+Plugin hoạt động trên cả ESLint và [oxlint](https://oxc.rs) — cùng quy tắc, cùng tùy chọn.
+
+<Tabs defaultTab="eslint">
+  <Tab label="ESLint" value="eslint">
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [...intlayer.configs.recommended];
+```
+
+Hoặc bật từng quy tắc một:
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [
+  {
+    plugins: { intlayer },
+    rules: {
+      "intlayer/no-raw-text": "warn",
+      "intlayer/static-dictionary-key": "error",
+      "intlayer/no-dynamic-field-access": "error",
+      "intlayer/enforce-adapter-import": "warn",
+      "intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+  </Tab>
+  <Tab label="oxlint" value="oxlint">
+
+```json fileName=".oxlintrc.json"
+{
+  "jsPlugins": ["eslint-plugin-intlayer"],
+  "rules": {
+    "intlayer/no-raw-text": "warn",
+    "intlayer/static-dictionary-key": "error",
+    "intlayer/no-dynamic-field-access": "error",
+    "intlayer/enforce-adapter-import": "warn"
+  }
+}
+```
+
+Hai lưu ý: hỗ trợ plugin JS của oxlint vẫn đang ở giai đoạn alpha và oxlint không hỗ trợ trình phân tích cú pháp tùy chỉnh — vì vậy các tệp `.vue`, `.svelte`, `.astro` và template Angular không được lint tại đó. Hãy chạy oxlint trên các tệp JS/TS/JSX của bạn và giữ lại ESLint cho phần còn lại.
+
+`no-unused-content` được cố tình lược bỏ ở trên: nó cần thư mục làm việc và đường dẫn tệp được lint từ ngữ cảnh quy tắc, điều mà cầu nối plugin JS alpha chưa đảm bảo. Hãy chạy quy tắc này dưới ESLint.
+
+  </Tab>
+</Tabs>
+
+### Cấu hình (Configs)
+
+| Cấu hình        | `no-raw-text`             | `static-dictionary-key` | `no-dynamic-field-access` | `enforce-adapter-import` | `no-unused-content` |
+| --------------- | ------------------------- | ----------------------- | ------------------------- | ------------------------ | ------------------- |
+| `recommended`   | warn                      | error                   | error                     | off                      | off                 |
+| `strict`        | error (+ chuỗi ngoài JSX) | error                   | error                     | error                    | off                 |
+| `contract-only` | off                       | error                   | error                     | off                      | off                 |
+
+`recommended` cố ý giữ `no-raw-text` ở mức `warn`: việc áp dụng quy tắc này vào một codebase hiện có sẽ hiển thị tất cả các chuỗi chưa được dịch cùng một lúc, điều này không nên làm gián đoạn bản build của bạn ngay từ ngày đầu tiên.
+
+`enforce-adapter-import` bị tắt theo mặc định — hãy bật rõ ràng nếu bạn muốn.
+
+`no-unused-content` bị tắt trong mọi cấu hình, bao gồm cả `strict`. Đây là quy tắc duy nhất đọc cấu hình Intlayer của bạn và duyệt qua các tệp nguồn từ đĩa, vì vậy việc bật nó nên là một lựa chọn có chủ đích thay vì được thiết lập sẵn tự động.
+
+## Các quy tắc
+
+### `no-raw-text`
+
+Báo cáo văn bản hiển thị cho người dùng không được khai báo trong từ điển. Quy tắc sử dụng cơ chế phát hiện giống như `intlayer extract`, do đó tên thương hiệu, lớp CSS và định danh kỹ thuật sẽ bị bỏ qua.
+
+```jsx
+// ✗ Bị báo cáo
+<h1>Welcome to our documentation</h1>
+<input placeholder="Enter your email address" />
+
+// ✓ Hợp lệ
+const { title } = useIntlayer("home");
+<h1>{title}</h1>
+```
+
+Các tệp khai báo nội dung (`*.content.ts`, …) được bỏ qua.
+
+Để sửa toàn bộ tệp cùng lúc, hãy chạy `npx intlayer extract` và để trình biên dịch chuyển các chuỗi vào từ điển giúp bạn.
+
+**Tùy chọn**
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+{
+  "intlayer/no-raw-text": [
+    "warn",
+    {
+      // Các thuộc tính có giá trị là văn bản hiển thị cho người dùng.
+      // Mặc định: title, placeholder, alt, aria-label, label
+      attributes: ["title", "placeholder", "alt", "aria-label", "label"],
+
+      // Các phần tử có nội dung không bao giờ là văn bản hiển thị cho người dùng.
+      // Mặc định: code, pre, script, style
+      ignoreElements: ["code", "pre", "script", "style"],
+
+      // Biểu thức chính quy cho văn bản không bao giờ bị báo cáo.
+      ignorePatterns: ["^Powered by"],
+
+      // Báo cáo cả chuỗi ký tự bên ngoài mã markup. Mặc định: false
+      includeStringLiterals: false,
+    },
+  ],
+}
+```
+
+### `static-dictionary-key`
+
+Yêu cầu khóa từ điển phải là một chuỗi ký tự cố định (string literal).
+
+Trình biên dịch chỉ có thể tải trước từ điển khi có thể đọc trực tiếp khóa tại vị trí gọi. Với một khóa được tính toán động, nó sẽ âm thầm bỏ qua việc tối ưu hóa và đóng gói tất cả từ điển thay thế.
+
+```typescript
+// ✗ Bị báo cáo
+useIntlayer(dictionaryKey);
+useIntlayer(`home-${suffix}`);
+getTranslations({ namespace: page });
+
+// ✗ Biến vẫn không phải là một chuỗi cố định
+const key = "home";
+useIntlayer(key);
+
+// ✓ Hợp lệ
+useIntlayer("home");
+getTranslations({ namespace: "home" });
+```
+
+Điều này áp dụng cho `useIntlayer`, `getIntlayer` và mọi adapter tương thích (`useTranslation`, `useTranslations`, `formatMessage`, `<FormattedMessage id>`, `<Trans i18nKey>`, …).
+
+### `no-dynamic-field-access`
+
+Yêu cầu trường bạn đọc từ từ điển phải được xác định tĩnh.
+
+Trình biên dịch sẽ loại bỏ các trường mà nó không thấy được sử dụng. Một truy cập được tính toán động là vô hình đối với nó, do đó việc đọc có thể trả về `undefined` trong thời gian chạy.
+
+```typescript
+// ✗ Bị báo cáo
+const content = useIntlayer("home");
+content[fieldName];
+
+const t = useTranslations("home");
+t(messageKey);
+
+// ✓ Hợp lệ
+content.title;
+content["title"];
+content.items[0];
+t("hero.title");
+```
+
+### `enforce-adapter-import`
+
+Ưu tiên adapter tương thích `@intlayer/*` hơn gói gốc. Gói gốc chỉ phân giải thành Intlayer khi alias của bundler được cấu hình; adapter luôn luôn thực hiện được. Có thể tự động sửa bằng `--fix`.
+
+```typescript
+// ✗ Bị báo cáo
+import { useTranslation } from "react-i18next";
+import { getTranslations } from "next-intl/server";
+
+// ✓ Hợp lệ
+import { useTranslation } from "@intlayer/react-i18next";
+import { getTranslations } from "@intlayer/next-intl/server";
+```
+
+### `no-unused-content`
+
+**Tắt theo mặc định.** Báo cáo nội dung không có bất kỳ phần nào trong dự án đọc, cùng với các khóa từ điển được khai báo ở nhiều nơi.
+
+```typescript fileName="src/home.content.ts"
+export default {
+  key: "home", // ✗ Bị báo cáo nếu không có nơi nào trong dự án yêu cầu "home"
+  content: {
+    title: t({ vi: "Tiêu đề", en: "Title" }),
+
+    // ✗ Bị báo cáo nếu không có nơi nào đọc `hero`
+    hero: {
+      subtitle: t({ vi: "Phụ đề", en: "Subtitle" }),
+    },
+  },
+};
+```
+
+Không giống như các quy tắc khác, quy tắc này không thể quyết định chỉ từ tệp đang kiểm tra — một trường chỉ được xem là không sử dụng khi so với toàn bộ dự án. Khi gặp khai báo nội dung đầu tiên trong một lần lint, nó sẽ tải cấu hình Intlayer, quét các tệp nguồn mà cấu hình đó khai báo (`build.traversePattern`, `compiler.transformPattern`) và chạy cùng bộ phân tích mức độ sử dụng đang vận hành `@intlayer/lsp` và tính năng gạch ngang "không sử dụng" trong tiện ích mở rộng VS Code. Kết quả được lưu vào bộ nhớ cache trong `cacheTtl` mili giây, do đó quá trình quét diễn ra một lần cho mỗi lượt chạy thay vì mỗi tệp.
+
+**Tùy chọn**
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+{
+  "intlayer/no-unused-content": [
+    "warn",
+    {
+      // Báo cáo các khóa từ điển không có nơi nào tham chiếu. Mặc định: true
+      reportUnusedDictionaries: true,
+
+      // Báo cáo các trường nội dung không có nơi nào đọc. Mặc định: true
+      reportUnusedFields: true,
+
+      // Báo cáo các khóa được khai báo ở nhiều nơi. Mặc định: true
+      reportDuplicateKeys: true,
+
+      // Biểu thức chính quy cho đường dẫn trường không bao giờ bị báo cáo.
+      ignoreFields: ["^meta"],
+
+      // Thư mục gốc của dự án bắt đầu quét. Mặc định: thư mục làm việc của ESLint
+      baseDir: process.cwd(),
+
+      // Thời gian một lần quét dự án được tái sử dụng, tính bằng ms. Mặc định: 30000
+      cacheTtl: 30000,
+    },
+  ],
+}
+```
+
+Giảm `cacheTtl` khi bạn lint từ một editor server hoạt động lâu dài và muốn các chỉnh sửa hiển thị sớm hơn; thiết lập `baseDir` khi một lần chạy lint trải rộng trên nhiều dự án Intlayer trong monorepo.
+
+> **Thiên về sự an toàn (ít báo sai).** Một cảnh báo sai ở đây có thể dẫn đến việc xóa một bản dịch, vì vậy sẽ không có gì được báo cáo khi từ điển được sử dụng theo cách mà bộ phân tích không thể theo dõi: đối tượng nội dung được truyền nguyên vẹn, hàm dịch được liên kết từ đó (`const t = useTranslations("home")`), khai báo được truy cập qua import trực tiếp (`useDictionary(myDictionary)`), lệnh `nest()` từ từ điển khác, hoặc danh sách trường bị làm mờ bởi toán tử spread. Các component đơn tệp (`.vue`, `.svelte`, `.astro`) được tính là sử dụng mọi trường của từ điển mà chúng đề cập, vì các khối script của chúng không được phân tích cú pháp tại đây.
+
+`reportDuplicateKeys` đọc các từ điển chưa hợp nhất mà bản build ghi dưới thư mục `.intlayer/`, do đó nó giữ im lặng cho đến khi dự án được build ít nhất một lần. Hai khai báo có chung một khóa sẽ được hợp nhất, đây là một mẫu hợp lệ — báo cáo tồn tại vì một trường được định nghĩa ở cả hai bên sẽ âm thầm chỉ giữ lại một trong hai giá trị.
+
+Bộ phân tích được nạp từ `@intlayer/lsp`, phát hành dưới dạng ESM. Do đó quy tắc cần một phiên bản Node có thể `require()` module ES — Node 20.19+ hoặc 22.12+. Trên các phiên bản cũ hơn, nó sẽ không báo cáo gì thay vì làm hỏng lần chạy lint.
+
+## Frameworks
+
+Mọi quy tắc đều hoạt động trên tất cả các tích hợp của Intlayer, bao gồm bên trong template của Vue, Svelte và Angular. Bạn chỉ cần chỉ định cho ESLint parser nào xử lý từng loại tệp.
+
+| Framework                 | Tệp               | Parser                            |
+| ------------------------- | ----------------- | --------------------------------- |
+| React, Preact, Solid, Lit | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Next.js                   | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Vue, Nuxt                 | `.vue`            | `vue-eslint-parser`               |
+| Svelte, SvelteKit         | `.svelte`         | `svelte-eslint-parser`            |
+| Angular                   | `.ts`             | `typescript-eslint`               |
+| Template Angular          | `.component.html` | `@angular-eslint/template-parser` |
+| Astro                     | `.astro`          | `astro-eslint-parser`             |
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+import tseslint from "typescript-eslint";
+import vueParser from "vue-eslint-parser";
+import svelteParser from "svelte-eslint-parser";
+import angularTemplateParser from "@angular-eslint/template-parser";
+
+export default [
+  ...intlayer.configs.recommended,
+
+  {
+    files: ["**/*.{ts,tsx,jsx}"],
+    languageOptions: { parser: tseslint.parser },
+  },
+  {
+    files: ["**/*.vue"],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.svelte"],
+    languageOptions: {
+      parser: svelteParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.component.html"],
+    languageOptions: { parser: angularTemplateParser },
+  },
+];
+```
+
+Chỉ cài đặt các parser mà dự án của bạn cần.
+
+> **Hạn chế đã biết.** Trong template của Vue và Angular, một biểu thức như `{{ content[key] }}` sẽ không được kiểm tra bởi `no-dynamic-field-access`. Các truy cập động được viết trong khối script vẫn được phát hiện bình thường.

package/docs/zh/eslint.md

@@ -0,0 +1,336 @@
+---
+createdAt: 2026-08-12
+updatedAt: 2026-08-12
+title: ESLint 插件 | Intlayer 的 Lint 规则
+description: 使用 eslint-plugin-intlayer 捕获硬编码字符串、Intlayer 编译器无法优化的动态调用以及未使用的字典内容。支持 ESLint 和 oxlint，适用于 React、Vue、Svelte、Angular 和 Astro。
+keywords:
+  - Intlayer
+  - ESLint
+  - oxlint
+  - 代码检查
+  - i18n
+  - 国际化
+  - no-raw-text
+  - 硬编码字符串
+  - 未使用的翻译
+  - 死内容
+  - React
+  - Vue
+  - Svelte
+  - Angular
+slugs:
+  - doc
+  - eslint
+history:
+  - version: 9.3.1
+    date: 2026-08-12
+    changes: "初始化历史"
+author: aymericzip
+---
+
+# ESLint x OXLint 插件
+
+`eslint-plugin-intlayer` 能够捕获 TypeScript 无法发现的几类 i18n 错误：
+
+1. **硬编码文本**：从未写入字典中的文本。
+2. **动态调用**：能够通过类型检查并正常运行，但 Intlayer 编译器无法进行优化的调用。
+3. **死内容（Dead content）**：项目中没有任何地方读取的字典和字段（需手动开启）。
+
+未知的字典键、未知的字段路径和缺失的语言环境本身已是编译错误，因此插件不会重复报告它们。
+
+## 安装
+
+```bash packageManager="npm"
+npm install --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add --save-dev eslint-plugin-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add --dev eslint-plugin-intlayer
+```
+
+需要 ESLint 9 或更高版本（Flat config）。
+
+## 使用方法
+
+该插件可在 ESLint 和 [oxlint](https://oxc.rs) 中运行 — 拥有相同的规则和配置选项。
+
+<Tabs defaultTab="eslint">
+  <Tab label="ESLint" value="eslint">
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [...intlayer.configs.recommended];
+```
+
+或者逐个启用规则：
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [
+  {
+    plugins: { intlayer },
+    rules: {
+      "intlayer/no-raw-text": "warn",
+      "intlayer/static-dictionary-key": "error",
+      "intlayer/no-dynamic-field-access": "error",
+      "intlayer/enforce-adapter-import": "warn",
+      "intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+  </Tab>
+  <Tab label="oxlint" value="oxlint">
+
+```json fileName=".oxlintrc.json"
+{
+  "jsPlugins": ["eslint-plugin-intlayer"],
+  "rules": {
+    "intlayer/no-raw-text": "warn",
+    "intlayer/static-dictionary-key": "error",
+    "intlayer/no-dynamic-field-access": "error",
+    "intlayer/enforce-adapter-import": "warn"
+  }
+}
+```
+
+两点注意事项：oxlint 对 JS 插件的支持仍处于 Alpha 阶段，且 oxlint 不支持自定义解析器 — 因此 `.vue`、`.svelte`、`.astro` 和 Angular 模板无法在此处进行 lint。请在 JS/TS/JSX 文件上运行 oxlint，其余文件保留使用 ESLint。
+
+上面特意排除了 `no-unused-content`：它需要从规则上下文中获取工作目录和被检查文件的路径，而 Alpha 阶段的 JS 插件桥接层无法保证提供这些信息。请在 ESLint 下运行该规则。
+
+  </Tab>
+</Tabs>
+
+### 预设配置
+
+| 配置            | `no-raw-text`           | `static-dictionary-key` | `no-dynamic-field-access` | `enforce-adapter-import` | `no-unused-content` |
+| --------------- | ----------------------- | ----------------------- | ------------------------- | ------------------------ | ------------------- |
+| `recommended`   | warn                    | error                   | error                     | off                      | off                 |
+| `strict`        | error (+ 非 JSX 字面量) | error                   | error                     | error                    | off                 |
+| `contract-only` | off                     | error                   | error                     | off                      | off                 |
+
+`recommended` 特意将 `no-raw-text` 设为 `warn`：将其指向现有代码库会一次性暴露所有未翻译的字符串，这不应该在第一天就导致构建中断。
+
+`enforce-adapter-import` 默认关闭 — 如果需要请显式启用。
+
+`no-unused-content` 在所有配置中均默认关闭（包括 `strict`）。这是唯一一个需要读取 Intlayer 配置并从磁盘遍历源文件的规则，因此启用它应当是一项经过深思熟虑的选择，而非预设自动执行的行为。
+
+## 规则列表
+
+### `no-raw-text`
+
+报告未在字典中声明的面向用户的文本。它使用与 `intlayer extract` 相同的检测逻辑，因此品牌名称、CSS 类名和技术标识符都会被忽略。
+
+```jsx
+// ✗ 报告错误
+<h1>Welcome to our documentation</h1>
+<input placeholder="Enter your email address" />
+
+// ✓ 正常
+const { title } = useIntlayer("home");
+<h1>{title}</h1>
+```
+
+内容声明文件（`*.content.ts`, …）会被跳过。
+
+若要一次性修复整个文件，运行 `npx intlayer extract`，让编译器自动将字符串移入字典。
+
+**配置选项**
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+{
+  "intlayer/no-raw-text": [
+    "warn",
+    {
+      // 值为面向用户文本的属性列表。
+      // 默认值: title, placeholder, alt, aria-label, label
+      attributes: ["title", "placeholder", "alt", "aria-label", "label"],
+
+      // 内容绝非面向用户文本的元素列表。
+      // 默认值: code, pre, script, style
+      ignoreElements: ["code", "pre", "script", "style"],
+
+      // 绝不报告的文本正则表达式。
+      ignorePatterns: ["^Powered by"],
+
+      // 是否同时报告标记语言之外的字符串字面量。默认值: false
+      includeStringLiterals: false,
+    },
+  ],
+}
+```
+
+### `static-dictionary-key`
+
+要求字典键必须是字符串字面量。
+
+编译器只有在调用位置直接读取到键时，才能预加载字典。使用计算键会静默跳过优化，转而打包所有字典。
+
+```typescript
+// ✗ 报告错误
+useIntlayer(dictionaryKey);
+useIntlayer(`home-${suffix}`);
+getTranslations({ namespace: page });
+
+// ✗ 变量仍然不是字面量
+const key = "home";
+useIntlayer(key);
+
+// ✓ 正常
+useIntlayer("home");
+getTranslations({ namespace: "home" });
+```
+
+这适用于 `useIntlayer`、`getIntlayer` 以及所有兼容适配器（`useTranslation`、`useTranslations`、`formatMessage`、`<FormattedMessage id>`、`<Trans i18nKey>` 等）。
+
+### `no-dynamic-field-access`
+
+要求从字典中读取的字段必须是静态已知的。
+
+编译器会移除它未检测到使用的字段。动态计算访问对其不可见，因此该读取在运行时可能会返回 `undefined`。
+
+```typescript
+// ✗ 报告错误
+const content = useIntlayer("home");
+content[fieldName];
+
+const t = useTranslations("home");
+t(messageKey);
+
+// ✓ 正常
+content.title;
+content["title"];
+content.items[0];
+t("hero.title");
+```
+
+### `enforce-adapter-import`
+
+优先使用 `@intlayer/*` 兼容适配器而非原始包。原始包仅在配置了打包工具别名时才会解析为 Intlayer；而适配器始终生效。可通过 `--fix` 自动修复。
+
+```typescript
+// ✗ 报告错误
+import { useTranslation } from "react-i18next";
+import { getTranslations } from "next-intl/server";
+
+// ✓ 正常
+import { useTranslation } from "@intlayer/react-i18next";
+import { getTranslations } from "@intlayer/next-intl/server";
+```
+
+### `no-unused-content`
+
+**默认关闭。** 报告项目中没有任何地方读取的内容，以及在多个位置声明的字典键。
+
+```typescript fileName="src/home.content.ts"
+export default {
+  key: "home", // ✗ 当项目中没有任何调用方请求 "home" 时报告
+  content: {
+    title: t({ zh: "标题", en: "Title" }),
+
+    // ✗ 当没有任何地方读取 `hero` 时报告
+    hero: {
+      subtitle: t({ zh: "副标题", en: "Subtitle" }),
+    },
+  },
+};
+```
+
+与其他规则不同，此规则无法仅凭眼前的文件给出判断 — 字段是否未使用仅相对于整个项目而言。在一次 lint 运行的首次内容声明时，它会加载你的 Intlayer 配置，匹配该配置声明的源文件（`build.traversePattern`、`compiler.transformPattern`），并运行驱动 `@intlayer/lsp` 和 VS Code 扩展中“未使用”删除线的同一套使用情况分析器。结果会缓存 `cacheTtl` 毫秒，因此每次运行只会扫描一次，而不是每个文件扫描一次。
+
+**配置选项**
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+{
+  "intlayer/no-unused-content": [
+    "warn",
+    {
+      // 报告没有任何地方引用的字典键。默认值: true
+      reportUnusedDictionaries: true,
+
+      // 报告没有任何地方读取的内容字段。默认值: true
+      reportUnusedFields: true,
+
+      // 报告在多处声明的重复键。默认值: true
+      reportDuplicateKeys: true,
+
+      // 绝不报告的字段路径正则表达式。
+      ignoreFields: ["^meta"],
+
+      // 扫描起始的项目根目录。默认值: ESLint 的工作目录
+      baseDir: process.cwd(),
+
+      // 项目扫描结果复用时长（毫秒）。默认值: 30000
+      cacheTtl: 30000,
+    },
+  ],
+}
+```
+
+如果你在长期运行的编辑器服务中进行 lint 且希望更快看到修改结果，可以降低 `cacheTtl`；当单次 lint 运行跨越 monorepo 中的多个 Intlayer 项目时，请设置 `baseDir`。
+
+> **倾向于保持沉默。** 此处的误报会导致翻译被误删，因此当字典以分析器无法跟踪的方式被使用时，不会报告任何内容：内容对象被整体传递、从中绑定的翻译函数（`const t = useTranslations("home")`）、通过直接导入访问的声明（`useDictionary(myDictionary)`）、来自另一个字典的 `nest()`、或者因 spread 展开而不详尽的字段列表。单文件组件（`.vue`、`.svelte`、`.astro`）计为使用了它们提及的字典中的所有字段，因为它们的脚本块在此处不会被解析。
+
+`reportDuplicateKeys` 读取构建时写入 `.intlayer/` 下的未合并字典，因此在项目至少构建过一次之前它会保持静默。共享一个键的两个声明会被合并，这是一种合法的模式 — 该报告之所以存在，是因为在两边同时定义的字段会静默保留两个值中的一个。
+
+分析器从以 ESM 形式分发的 `@intlayer/lsp` 中加载。因此该规则需要能够 `require()` ES 模块的 Node 版本 — Node 20.19+ 或 22.12+。在更低版本上，它不会报错中断 lint 运行，而是什么都不报告。
+
+## 框架支持
+
+每条规则均适用于所有 Intlayer 集成，包括 Vue、Svelte 和 Angular 模板内部。你只需告诉 ESLint 哪个解析器负责读取对应的文件类型即可。
+
+| 框架                      | 文件              | 解析器                            |
+| ------------------------- | ----------------- | --------------------------------- |
+| React, Preact, Solid, Lit | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Next.js                   | `.jsx` `.tsx`     | `typescript-eslint`               |
+| Vue, Nuxt                 | `.vue`            | `vue-eslint-parser`               |
+| Svelte, SvelteKit         | `.svelte`         | `svelte-eslint-parser`            |
+| Angular                   | `.ts`             | `typescript-eslint`               |
+| Angular 模板              | `.component.html` | `@angular-eslint/template-parser` |
+| Astro                     | `.astro`          | `astro-eslint-parser`             |
+
+```javascript fileName="eslint.config.mjs" codeFormat="esm"
+import intlayer from "eslint-plugin-intlayer";
+import tseslint from "typescript-eslint";
+import vueParser from "vue-eslint-parser";
+import svelteParser from "svelte-eslint-parser";
+import angularTemplateParser from "@angular-eslint/template-parser";
+
+export default [
+  ...intlayer.configs.recommended,
+
+  {
+    files: ["**/*.{ts,tsx,jsx}"],
+    languageOptions: { parser: tseslint.parser },
+  },
+  {
+    files: ["**/*.vue"],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.svelte"],
+    languageOptions: {
+      parser: svelteParser,
+      parserOptions: { parser: tseslint.parser },
+    },
+  },
+  {
+    files: ["**/*.component.html"],
+    languageOptions: { parser: angularTemplateParser },
+  },
+];
+```
+
+请仅安装项目所需的解析器。
+
+> **已知局限性。** 在 Vue 和 Angular 模板中，类似于 `{{ content[key] }}` 的表达式不会被 `no-dynamic-field-access` 检查。写在 script 块中的动态读取仍会被正常捕获。

package/docs/zh/intlayer_with_create_react_app.md

@@ -612,6 +612,10 @@ export default App;
 - 根据语言环境调整 **文本方向** (`dir`)，提升不同阅读顺序语言的可读性和可用性。
 - 提供更 **无障碍** 的体验，因为辅助技术依赖这些属性以实现最佳功能。
 
+  </Step>
+
+</Steps>
+
 ### 配置 TypeScript
 
 Intlayer 使用模块增强来利用 TypeScript 的优势，使您的代码库更强大。