企业官网建设流程全解析

• 代码质量
• CI/CD

NATURAL_LANGUAGE 是 super-linter 中专门用于对 Markdown 文档进行自然语言拼写与文风检查的 lint 语言模块，其底层引擎为 textlint。本文围绕该模块在 super-linter 中的完整工作链路展开：从测试用例的设计意图（bad/good 文件），到源码中文件的收集、规则配置文件的解析，再到 textlint 命令的实际拼装，帮助你理解如何在 CI 中为中文/英文文档配置并启用自然语言检查，并掌握从仓库源码定位配置与验证行为的方法。

该模块解决的痛点：Markdown 拼写与文风问题

在软件开发流程中，代码本身可以被各种 linter 约束，但仓库里的 Markdown 文档（README、CHANGELOG、docs 等）却常常缺乏自动化质量保障。自然语言文档中最常见的两类问题：

• 拼写/大小写错误：例如把JavaScript写成Javascript、changelogs写成change logs；
• 专有名词与术语不统一：例如source maps与source-maps混用。

super-linter 的 NATURAL_LANGUAGE 模块正是为这类问题而生：它借助 textlint 对 Markdown 文本进行规则化校验，让文档质量和代码质量一样可控。

测试用例设计：bad 与 good 文件如何定义“对与错”

super-linter 的每个语言模块在 test/linters 下都维护一套测试用例，命名约定如下：文件名或路径中包含good的用例应通过校验，包含bad的用例应被判定为失败。NATURAL_LANGUAGE 模块的两个测试文件恰好展示了 textlint 能捕获的真实问题：

test/linters/natural_language/natural_language_bad_01.md（期望 lint 失败）内容如下：

My **Javascript** is good Write change logs about source-maps

test/linters/natural_language/natural_language_good_01.md（期望 lint 通过）内容如下：

My **JavaScript** is good Write changelogs about source maps

对照两个文件可以清晰看出该模块的校验目标：

从 test/linters/README.md 可知，测试只关注 super-linter 如何调用每个 linter 及其退出码，不校验 linter 的具体输出内容——这是各 linter 自身职责。因此这两个文件本质上是给“super-linter 是否把 Markdown 交给 textlint 并正确传播退出码”做回归验证。

文件收集：哪些 Markdown 会进入 NATURAL_LANGUAGE 队列

NATURAL_LANGUAGE 检查的输入由 lib/functions/buildFileList.sh 决定。在文件类型分发的elif链中，md扩展名分支如下（见 buildFileList.sh 第 706-713 行）：

elif [ "${FILE_TYPE}" == "md" ]; then echo "${FILE}" >>"${FILE_ARRAYS_DIRECTORY_PATH}/file-array-MARKDOWN" if IsNotSymbolicLink "${FILE}"; then echo "${FILE}" >>"${FILE_ARRAYS_DIRECTORY_PATH}/file-array-MARKDOWN_PRETTIER" else debug "Skip adding ${FILE} to MARKDOWN_PRETTIER file array because Prettier doesn't support following symbolic links" fi echo "${FILE}" >>"${FILE_ARRAYS_DIRECTORY_PATH}/file-array-NATURAL_LANGUAGE"

可以看出：

• 每个.md文件会同时进入 MARKDOWN（markdownlint）、MARKDOWN_PRETTIER（Prettier）与 NATURAL_LANGUAGE（textlint）三个文件数组，三者互不替代；
• 与 Prettier 分支不同，NATURAL_LANGUAGE 不排除符号链接文件，即所有被检测到的.md文件都会进入 textlint 检查队列；
• 文件是否进入该队列与是否自定义规则无关，属于全局文件发现流程的一部分。

规则配置：.textlintrc的查找与回退机制

NATURAL_LANGUAGE 的规则文件默认名为.textlintrc，这一默认值定义在 lib/globals/linterRules.sh 第 106 行：

NATURAL_LANGUAGE_FILE_NAME="${NATURAL_LANGUAGE_CONFIG_FILE:-.textlintrc}"

也就是说，你可以通过环境变量NATURAL_LANGUAGE_CONFIG_FILE覆盖默认文件名。而规则文件的实际路径解析逻辑在 lib/functions/linterRules.sh 的LinterRules函数中（见第 16-73 行），其核心行为：

1. 若LINTER_RULES_PATH为.或/，则将其置空（第 6-7 行），即不再拼接子目录；
2. 当LINTER_RULES_PATH非空时，规则路径解析为${GITHUB_WORKSPACE}/${LINTER_RULES_PATH}/${NATURAL_LANGUAGE_FILE_NAME}（第 36 行）；
3. 当LINTER_RULES_PATH为空时，回退到镜像内置路径${DEFAULT_RULES_LOCATION}/${NATURAL_LANGUAGE_FILE_NAME}（第 49 行），其中DEFAULT_RULES_LOCATION在 lib/globals/linterRules.sh 第 5 行 定义为/action/lib/.automation；
4. 若解析出的规则文件不存在，除 Java 的少数内置兜底外，会调用fatal终止（第 70 行），保证配置缺失时快速失败而不是静默降级。

LINTER_RULES_PATH的默认值是.github/linters（lib/globals/linterRules.sh 第 8 行），这也是绝大多数 super-linter 语言模块共用的规则目录约定。因此，在你的仓库中放置.github/linters/.textlintrc即可让该配置对 NATURAL_LANGUAGE 生效。

命令拼装：textlint 如何被调用

NATURAL_LANGUAGE 的实际执行命令定义在 lib/functions/linterCommands.sh 第 216 行：

LINTER_COMMANDS_ARRAY_NATURAL_LANGUAGE=(textlint -c "${NATURAL_LANGUAGE_LINTER_RULES}")

这条命令与相邻的 MARKDOWN 命令（markdownlint -c ...）保持一致的风格：通过-c显式指定配置文件路径（即上一步LinterRules函数解析出的${NATURAL_LANGUAGE_LINTER_RULES}变量值），其余参数由 worker 统一追加。因此最终对每个.md文件执行的实质命令为：

textlint -c <规则文件路径> <markdown文件>

此外，在 lib/globals/linterCommandsOptions.sh 第 78 行 中定义了修复模式选项：

NATURAL_LANGUAGE_FIX_MODE_OPTIONS=(--fix)

当开启 super-linter 的 FIX_MODE 时，textlint 会以--fix参数运行，自动修复可自动处理的拼写/文风问题；不可自动修复的问题仍会以失败退出。这是该模块与普通 lint 模式最大的行为差异。

工作流全景与实操建议

综合以上源码证据，NATURAL_LANGUAGE 的完整工作链路为：

文件发现（buildFileList.sh，收集所有 .md） → 规则定位（linterRules.sh，解析 .textlintrc） → 命令拼装（linterCommands.sh，textlint -c ...） → 执行与退出码传播（worker） → 失败时产出检查报告

实操要点总结如下：

1. 启用方式：无需额外开关，任何.md文件默认都会被 NATURAL_LANGUAGE 检查；若想跳过，可结合 super-linter 的 FILTER_REGEX_INCLUDE/EXCLUDE 配置，但这会同时影响其他模块的文件收集。
2. 自定义规则：在仓库根目录创建.github/linters/.textlintrc（JSON 格式的 textlint 配置），即可替换镜像内置默认配置；如不想使用该默认目录，可通过LINTER_RULES_PATH与NATURAL_LANGUAGE_CONFIG_FILE两个环境变量调整查找位置与文件名。
3. 配置缺失行为：若解析出的.textlintrc不存在，super-linter 会直接fatal终止而不是跳过，因此使用自定义规则前务必保证文件真实存在。
4. 修复模式：在 FIX_MODE 下 textlint 会以--fix运行，可对部分拼写问题自动修复；建议将 bad/good 两个测试用例（natural_language_bad_01.md 与 natural_language_good_01.md）作为本地验证的最小样例。
5. 回归验证：若你 fork 或扩展了 NATURAL_LANGUAGE 相关逻辑，可运行 test/run-super-linter-tests.sh 中对应的测试套件，确认 textlint 的退出码被正确传播。

综上，NATURAL_LANGUAGE 是 super-linter 中"文本即代码"理念的具体落地：通过统一的文件收集、规则定位与命令拼装机制，把 textlint 无缝接入 GitHub Action 的 lint 流水线，让 Markdown 文档的拼写、大小写与术语风格在合并前就能被自动化拦截。

• 代码质量
• CI/CD