cspell

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cspell

Prioritized strategy for handling cspell unknown word warnings. Classify each flagged word, pick the narrowest fix, and optionally bootstrap cspell config for projects that don't have it yet.

处理cspell未知单词警告的优先策略。对每个标记的单词进行分类，选择最窄范围的修复方案，并可选择为尚未配置cspell的项目初始化配置。

Core Principles

核心原则

Config Check First — Verify repo has cspell config before any action; offer bootstrap if missing
Adjust Text Before Adding to Dictionary — Restructure words (hyphenate, camelCase) when safe
Narrowest Scope Wins — Inline directive for one-off words; project dictionary for recurring terms

Documentation: Fetch cspell syntax and config details via Context7 (
/streetsidesoftware/cspell
) at runtime; never rely on hardcoded syntax.

先检查配置 — 在执行任何操作前，确认仓库是否有cspell配置；如果缺失，提供初始化选项
先调整文本再添加到字典 — 在安全的情况下重构单词（添加连字符、使用驼峰式命名）
最窄范围优先 — 一次性单词使用内联指令；重复出现的术语使用项目级字典

文档说明：运行时通过Context7（
/streetsidesoftware/cspell
）获取cspell语法和配置细节；切勿依赖硬编码的语法。

When to Use

适用场景

cspell flags an unknown word (IDE diagnostic or CI output)
User asks to fix cspell warnings, add words to dictionary, or suppress cspell errors
User wants to set up cspell in a project that doesn't have it
User asks why a word is flagged or wants to understand cspell behavior
Linting pipeline or pre-commit hook fails due to unrecognized words

When NOT to use: For non-cspell spell checkers (typo, codespell, Vale, textlint). For other linting tools (ESLint, markdownlint), use their respective strategies.

cspell标记了未知单词（IDE诊断或CI输出）
用户要求修复cspell警告、将单词添加到字典，或抑制cspell错误
用户希望在尚未配置cspell的项目中设置该工具
用户询问某个单词被标记的原因，或想要了解cspell的行为
代码检查流水线或提交前钩子因未识别单词而失败

不适用场景：非cspell的拼写检查工具（如typo、codespell、Vale、textlint）。对于其他代码检查工具（如ESLint、markdownlint），请使用各自的处理策略。

Workflow

工作流程

Check for cspell config — Search from the file's directory upward for cspell config files:
```
package.json
```
(
```
cspell
```
field),
```
.cspell.json
```
,
```
cspell.json
```
,
```
cspell.config.{json,mjs,js,cjs,yaml,yml,toml}
```
,
```
cspell.{yaml,yml}
```
, and their
```
.
```
/
```
.config/
```
prefixed variants (e.g.,
```
.cspell.config.yaml
```
,
```
.config/cspell.json
```
). Also check
```
.vscode/cspell.json
```
. If none found: notify user, do NOT auto-fix, offer to bootstrap (see below). Note:
```
cspell.*
```
settings in
```
.vscode/settings.json
```
are IDE-local and do not count as project config.
Apply fix priority — Stop at the first applicable level (see table below).
Select directive — When using inline directives, consult decision-tree.md for the selection guide.

检查cspell配置 — 从文件目录向上搜索cspell配置文件：
```
package.json
```
（
```
cspell
```
字段）、
```
.cspell.json
```
、
```
cspell.json
```
、
```
cspell.config.{json,mjs,js,cjs,yaml,yml,toml}
```
、
```
cspell.{yaml,yml}
```
，以及带
```
.
```
/
```
.config/
```
前缀的变体（例如
```
.cspell.config.yaml
```
、
```
.config/cspell.json
```
）。同时检查
```
.vscode/cspell.json
```
。如果未找到：通知用户，不要自动修复，提供初始化选项（见下文）。注意：
```
.vscode/settings.json
```
中的
```
cspell.*
```
设置仅适用于本地IDE，不算作项目级配置。
应用修复优先级 — 找到第一个适用的修复级别后停止（见下表）。
选择指令 — 使用内联指令时，请参考decision-tree.md中的选择指南。

Fix Priority

修复优先级

Priority	Strategy	When to Use
1	Adjust text	Compound word cspell doesn't recognize; restructuring is safe (hyphenate, camelCase). See decision-tree.md for the full exception list
2	Project dictionary	Word appears in 2+ files or is expected to recur project-wide
3	Inline directive	One-off word in a single file/location. See decision-tree.md for directive selection and placement

优先级	策略	适用场景
1	调整文本	cspell无法识别的复合词；重构操作是安全的（添加连字符、使用驼峰式命名）。完整的例外列表请参考decision-tree.md
2	项目级字典	单词出现在2个及以上文件中，或预计会在项目范围内重复出现
3	内联指令	单个文件/位置中的一次性单词。指令的选择和放置请参考decision-tree.md

Config Bootstrapping

配置初始化

When a repo has no cspell config and the user wants to add one, guide through an interactive Q&A flow.

See config-bootstrapping.md for the full interactive setup flow.

当仓库没有cspell配置且用户想要添加时，引导用户完成交互式问答流程。

完整的交互式设置流程请参考config-bootstrapping.md。

Guidelines

指导原则

DO

建议做

Check repo config before any action
Prefer text adjustment over dictionary pollution
Use narrowest scope directive that fits
Place
```
cspell:words
```
at file top for discoverability
Verify the flagged word is genuinely unknown (not a missing dictionary)

在执行任何操作前检查仓库配置
优先调整文本，避免污染字典
使用符合需求的最窄范围指令
将
```
cspell:words
```
放在文件顶部，便于查找
确认标记的单词确实是未知词汇（而非缺少对应字典）

DON'T

禁止做

Replace words with semantically different alternatives
Add one-off words to project dictionary (use inline directives)
Use
```
cspell:disable
```
to suppress large sections when individual words can be handled
Blindly accept all cspell suggestions — some flagged words are correct
Hyphenate or restructure runtime API identifiers, package names, or fixed external terms

用语义不同的词汇替换原词
将一次性单词添加到项目级字典（使用内联指令）
当可以单独处理每个单词时，使用
```
cspell:disable
```
来抑制大段内容的检查
盲目接受所有cspell建议 — 有些标记的单词是正确的
对运行时API标识符、包名或固定外部术语添加连字符或重构

Error Handling

错误处理

Error	Action
No write permission to config	Notify user, suggest manual edit path
Excessive `cspell .` output	Scope to source directory, configure `ignorePaths` first
Context7 unavailable	Fall back to cspell.org or `cspell init --help`

For bootstrapping-specific errors (
cspell
CLI not installed,
cspell init
fails), see config-bootstrapping.md.

错误	操作
没有配置文件的写入权限	通知用户，建议手动编辑路径
`cspell .` 输出内容过多	限定到源码目录，先配置 `ignorePaths`
Context7不可用	回退到cspell.org或 `cspell init --help`

初始化相关错误（如未安装cspell CLI、
cspell init
执行失败），请参考config-bootstrapping.md。

Reference Files

参考文件

decision-tree.md — Full decision flowchart, text adjustment rules and exceptions, dictionary vs inline criteria, directive selection, edge cases
config-bootstrapping.md — Interactive setup flow, stack detection, CI integration, post-init adjustments

decision-tree.md — 完整的决策流程图、文本调整规则及例外情况、字典与内联指令的选择标准、指令选择、边缘案例
config-bootstrapping.md — 交互式设置流程、栈检测、CI集成、初始化后调整