# General Translation React SDKs (gt-react, gt-next): Lint 规则
URL: https://generaltranslation.com/zh/docs/react/reference/lint-rules.mdx
---

title: Lint 规则
description: 用于确保可翻译内容保持静态且正确的 General Translation React Core linter 规则参考。React Core linter 规则的 API 参考。

---

General Translation React Core linter (`@generaltranslation/react-core-linter`) 是一个 ESLint 插件，用于捕获常见的集成错误：可翻译组件中的动态内容、翻译函数中的非静态字符串，以及不受支持的属性。它的 `recommended` 配置会将所有规则都作为错误启用，其中三条规则里有两条支持自动修复。有关安装和 ESLint 设置，请参阅[对代码进行 Lint 检查](/docs/react/guides/linting-your-code)指南。

*这些规则会根据导入 source 来识别 General Translation 的组件和函数。默认识别 `gt-react`、`gt-next` 和 `gt-react-native`；你也可以通过 [`libs`](#libs) 选项添加其他包，例如 `gt-tanstack-start`。*

## 规则 [#rules]

| 规则                                          | 标记内容                                                                                                                                                                        | 自动修复 |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| [`static-string`](#static-string)           | 传递给翻译函数的动态或非静态字符串 ([`useGT`](/docs/react/reference/hooks/use-gt)、[`getGT`](/docs/node/reference/functions/get-gt)、[`msg`](/docs/react/reference/functions/msg)) ，以及非静态语法糖变量。 | 是    |
| [`static-jsx`](#static-jsx)                 | [`<T>`](/docs/react/reference/components/t) 中未包裹在 变量组件 中的动态内容。                                                                                                | 是    |
| [`no-data-attrs-on-branch`](#no-data-attrs) | [`<Branch>`](/docs/react/reference/components/branch) 上的 `data-*` 属性，这些属性会被该组件忽略。                                                                                           | 否    |

这三条规则在 `recommended` 配置中均设为 `error`，并且都接受共享的 [`libs`](#libs) 选项。

## `static-string` [#static-string]

**自动修复** 是 · **推荐** `error`

`gt` (来自 [`useGT`](/docs/react/reference/hooks/use-gt) 或 `getGT`) 和 [`msg`](/docs/react/reference/functions/msg) 等注册函数只能接受静态字符串，因为编译器会在构建时提取它们的内容。此规则会标记动态的第一个参数，并引导你改用 ICU 风格的插值：通过选项对象传入变量，而不是将变量拼接进字符串中。

### 工作原理

* **必须是静态内容。** 第一个参数必须是字符串字面量 (对于 [`msg`](/docs/react/reference/functions/msg)，则必须是字符串字面量数组) 。字符串拼接和插入变量的模板字面量都会被标记。
* **ICU 自动修复。** 当格式为 ICU (默认格式) 时，该规则会将可修复的动态表达式重写为 ICU 字符串加上一个选项对象。三元表达式会变为 `select` 语句，其他表达式会变为 `{varN}` 占位符。
* **允许使用 [`derive`](/docs/react/reference/functions/derive)。** [`derive`](/docs/react/reference/functions/derive) 调用——无论是单独使用，还是与静态部分拼接——都是允许的，因为它的变体会在构建时解析。
* **静态语法糖变量。** 选项对象中的元数据键必须是静态的，但各自要求的类型不同：`$id` 和 `$format` 必须是静态字符串，`$context` 必须是静态字符串或 [`derive`](/docs/react/reference/functions/derive) 调用，`$maxChars` 必须是数字字面量，`$requiresReview` 必须是布尔字面量。
* **ICU 验证。** 当字符串使用 ICU 格式时，该规则会验证其语法，并在消息格式不正确时报错 `Invalid ICU message format`。

### 示例

```tsx
// ❌ 错误 — 动态值通过字符串拼接传入
const gt = useGT();
gt('Hello ' + name);
gt(`Hello ${name}!`);

// ✅ 正确 — 使用 ICU 插值，变量通过 选项对象 传入
const gt = useGT();
gt('Hello {name}!', { name });
```

```tsx
// ❌ 错误 — 语法糖变量不是静态字符串
msg('Save', { $context: label });

// ✅ 正确 — 静态语法糖变量
msg('Save', { $context: 'a button label' });

// ✅ 正确 — 使用 derive 的构建时变体
gt('Hello ' + derive(getName()));
```

### 选项

支持共享的 [`libs`](#libs) 选项。

## `static-jsx` [#static-jsx]

**自动修复** 是 · **推荐** `error`

[`<T>`](/docs/react/reference/components/t) 组件只能包含静态子元素，以便编译器提取这些内容。此规则会标记 `<T>` 中的动态内容——变量、函数调用、成员表达式——并要求将其包裹在变量组件中：[`<Var>`](/docs/react/reference/components/var)、[`<Num>`](/docs/react/reference/components/num)、[`<Currency>`](/docs/react/reference/components/currency) 或 [`<DateTime>`](/docs/react/reference/components/datetime)。

### 工作方式

* **仅允许静态子元素。** 在 `<T>` 内，只允许使用字符串、数字、布尔值以及不含插值的模板字面量。任何其他表达式都会被标记。
* **自动包裹到 `<Var>` 中。** 被标记的表达式会被包裹到 [`<Var>`](/docs/react/reference/components/var) 中 (如有需要会自动导入) ，这样该值会被正常渲染，但不会被翻译。
* **分支转换。** 三元表达式 (`cond ? a : b`) 或逻辑与表达式 (`cond && a`) 会被转换为 [`<Branch>`](/docs/react/reference/components/branch)。
* **分支属性。** 该规则还会检查 [`<Branch>`](/docs/react/reference/components/branch) 和 [`<Plural>`](/docs/react/reference/components/plural) 的内容分支，并要求每个分支的值都必须是静态内容或 JSX。

### 示例

```tsx
// ❌ 错误 — 动态内容直接放在 <T> 内部
<T>{name}</T>;
<T>{getGreeting()}</T>;

// ✅ 正确 — 动态内容包裹在 变量组件 中
<T><Var>{name}</Var></T>;
<T>You have <Num>{count}</Num> messages.</T>;
```

```tsx
// ❌ 错误 — <T> 内部存在内联条件表达式
<T>{isActive ? 'Active' : 'Inactive'}</T>;

// ✅ 正确 — 自动修复会将其转换为 <Branch>
<T>
  <Branch branch={isActive} true="Active">Inactive</Branch>
</T>;
```

### 选项

支持共享的 [`libs`](#libs) 选项。

## `no-data-attrs-on-branch` [#no-data-attrs]

**自动修复** 否 · **推荐** `error`

[`<Branch>`](/docs/react/reference/components/branch) 组件会忽略所有带 `data-` 前缀的属性，因为它会将非保留属性视为 branch 值。此规则会标记 `<Branch>` 上的 `data-*` 属性，以免它们被悄然丢弃。此规则不提供自动修复；请删除该属性，或将其移到外层包裹元素上。

### 示例

```tsx
// ❌ 错误 — data-* 属性会被 <Branch> 忽略
<Branch branch={status} data-testid="status" active="Active" inactive="Inactive" />;

// ✅ 正确 — 将属性移至外层包裹元素
<span data-testid="status">
  <Branch branch={status} active="Active" inactive="Inactive" />
</span>;
```

### 选项

支持共享的 [`libs`](#libs) 选项。

## 选项 [#options]

每条规则都支持相同的选项。

### `libs` [#libs]

**类型** `string[]` · **可选** · **默认值** `['gt-react', 'gt-next', 'gt-react-native', 'gt-i18n', '@generaltranslation/react-core/components', '@generaltranslation/react-core/components-rsc', '@generaltranslation/react-core/hooks', '@generaltranslation/react-core/pure']`

该列表用于指定规则应视为 General Translation 包的模块来源。只有当组件或函数从这些模块之一导入时，才会被检查，因此也能正确解析别名导入。当你的框架包不在默认列表中时，请将其添加到这里——例如：`gt-tanstack-start`：

```js title="eslint.config.js"
const libs = ['gt-tanstack-start'];

export default [
  {
    plugins: { '@generaltranslation/react-core-linter': gtLint },
    rules: {
      '@generaltranslation/react-core-linter/static-jsx': ['error', { libs }],
      '@generaltranslation/react-core-linter/static-string': ['error', { libs }],
      '@generaltranslation/react-core-linter/no-data-attrs-on-branch': ['error', { libs }],
    },
  },
];
```