@intlayer/docs 9.3.1 → 9.3.3

package/docs/zh/eslint.md

@@ -0,0 +1,336 @@
+---
+createdAt: 2026-08-12
+updatedAt: 2026-08-13
+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 10。
+
+## 使用方法
+
+该插件可在 ESLint 和 [oxlint](https://oxc.rs) 中运行 — 拥有相同的规则和配置选项。
+
+<Tabs defaultTab="eslint">
+  <Tab label="ESLint" value="eslint">
+
+```javascript fileName="eslint.config.mjs"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [...intlayer.configs.recommended];
+```
+
+或者展开某个配置并自行设置严重级别：
+
+```javascript fileName="eslint.config.mjs"
+import intlayer from "eslint-plugin-intlayer";
+
+export default [
+  ...intlayer.configs.recommended,
+  {
+    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"
+{
+  "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"
+{
+  "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"
+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 的优势，使您的代码库更强大。

package/docs/zh/intlayer_with_lynx+react.md

@@ -67,6 +67,10 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
+<Steps>
+
+<Step number={1} title="安装依赖">
+
 ### Packages
 
 - **intlayer**  

package/docs/zh/intlayer_with_nextjs_14.md

@@ -531,8 +531,6 @@ const ServerComponentExample: FC = () => {
 
 > 若要了解有关 `useIntlayer` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useIntlayer.md)。
 
-<Steps>
-
 </Step>
 
 <Step number={8} title="元数据的国际化">

package/docs/zh/intlayer_with_nextjs_15.md

@@ -433,8 +433,6 @@ export const ServerComponentExample: FC = () => {
 
 > 要了解有关 `useIntlayer` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useIntlayer.md)。
 
-<Steps>
-
 </Step>
 
 <Step number={7} title="配置中间件以检测语言环境">

package/docs/zh/intlayer_with_nextjs_page_router.md

@@ -514,8 +514,6 @@ const ComponentExample = () => {
 
 > 要了解有关 `useIntlayer` 钩子的更多信息，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/next-intlayer/useIntlayer.md)。
 
-<Steps>
-
 </Step>
 
 <Step number={8} title="元数据的国际化">

package/docs/zh/intlayer_with_nuxt.md

@@ -314,7 +314,7 @@ Intlayer 提供了多种 API 来访问您的内容：
   - 使用 `const content = useIntlayer("myContent");` 以及 `{{ content.myContent }}` / `<content.myContent />`。
   - 或者使用 `const { myContent } = useIntlayer("myContent");` 以及 `{{ myContent}}` / `<myContent/>` 来解构内容。
 
-<Steps>
+</Step>
 
 <Step number={6} title="更改内容语言">
 

package/docs/zh/intlayer_with_react_router_v7.md

@@ -198,6 +198,10 @@ export default config;
 
 > 通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
+<Steps>
+
+<Step number={5} title="创建根布局">
+
 #### 根布局
 
 ```tsx fileName="app/root.tsx"

package/docs/zh/intlayer_with_react_router_v7_fs_routes.md

@@ -131,6 +131,10 @@ export default config;
 
 > 通过此配置文件，您可以设置本地化的 URL、中间件重定向、cookie 名称、内容声明的位置和扩展名，禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参阅[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
 
+<Steps>
+
+<Step number={5} title="创建根布局">
+
 #### 文件结构
 
 ```bash

package/docs/zh/intlayer_with_solid_start.md

@@ -572,7 +572,7 @@ export const Nav: Component = () => {
 
 <Step number={10} title="创建语言切换器组件">
 
-将切换器渲染为**真实的 <a> 锚点**而非 `<select>`：当前页面的每种语言都会变为可爬取的链接，并且可以在新标签页中打开，这是仅依靠 JavaScript 的控件无法提供的。
+将切换器渲染为**真实的 `<a>` 锚点**而非 `<select>`：当前页面的每种语言都会变为可爬取的链接，并且可以在新标签页中打开，这是仅依靠 JavaScript 的控件无法提供的。
 
 `getPathWithoutLocale` 会从当前路径中剥离语言段，而 `getLocalizedUrl` 会为目标语言重新构建它，因此这些链接会遵循你的路由模式，无需硬编码任何内容。导航是改变渲染语言的原因 —— `[[locale]]` 路由从 URL 中推导语言 —— 而 `setLocale` 会将选择保存在 `INTLAYER_LOCALE` cookie 中，以便以后访问无语言前缀的 URL 时能解析为相同的语言。
 

package/docs/zh/intlayer_with_vite+vue.md

@@ -444,8 +444,6 @@ Intlayer 提供了多种 API 来访问您的内容：
 
 > 如果您的应用程序已经存在，您可以结合使用 [Intlayer 编译器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/compiler.md) 和 [提取命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/extract.md) 在一秒钟内转换成干个组件。
 
-<Steps>
-
 </Step>
 
 <Step number={6} title="更改内容语言">

package/docs/zh-TW/bundle_optimization.md

@@ -159,7 +159,7 @@ pnpm add -D webpack-bundle-analyzer
 bun add -d webpack-bundle-analyzer
 ```
 
-```typescript fileName="webpack.config.ts
+```typescript fileName="webpack.config.ts"
 import { BundleAnalyzerPlugin } from "webpack-bundle-analyzer";
 
 export default {