使用 Vale 进行散文检查

写作是一个耗时的过程。根据作者和审阅流程的不同，内容可能需要一段时间才能准备好发布。无论您是独立作者还是大型团队，散文检查工具都可以帮助确保内容的一致语调和风格。

与代码检查工具类似，散文检查工具会自动检查您的文本中的错误。与突出语法规则违规的语法检查器不同，散文检查工具侧重于如何通过解决常见的用法问题来改进您的文本，例如多余的空格、重复的词语、过度使用行话、歧视性语言和不正确的字母大小写。

散文检查工具还可以为创建和执行编辑风格指南提供框架。这有助于审阅过程，因为您现在可以专注于审阅内容本身，而不是指出拼写错误和首选用法模式。这在 Meilisearch 这样的开源项目中尤为重要，因为您有许多不熟悉您风格指南的贡献者。

什么是 Vale？

Vale 是一个开源、高度可定制、语法感知的散文检查工具。它支持多种不同格式的文档，例如 Markdown、HTML、reStructuredText、AsciiDoc、DITA 和 XML。

在散文检查方面，Vale 并非您的唯一选择。还有许多其他开源工具可用，包括 proselint、textlint 和 alex。

在 Meilisearch，我们决定选择 Vale，因为它速度快、易于设置、灵活，并且带有现有规则可帮助您入门。

从何开始？

尽管看起来可能令人望而生畏，但如果您从小处着手并保持简单，设置 Vale 会相当简单。本文将介绍如何在类似于 Meilisearch 的文档的项目中使用 Vale。

步骤 1：风格指南

第一步是创建风格指南。无论您的团队规模多大，风格指南都能确保语调和风格的一致性。它在人们可能持有不同意见时（例如是否使用牛津逗号）建立了标准做法。

如果您没有内部风格指南，可以查看 Google 的或 Microsoft 的以帮助您入门。随着时间的推移，您会记住大部分规则，但有时可能会忽略错误，甚至完全忘记规则。我们毕竟是人。

这就是 Vale 的用武之地。它允许您“编纂”风格指南，并根据该风格指南中的所有规则检查您的文本。如果检测到任何问题，它会在控制台上显示建议、警告或错误。

步骤 2：安装 Vale

我使用的是 macOS，并在控制台中运行了 brew install vale 来安装 Vale。

如果您使用的是不同的操作系统，请查看 Vale 的文档以获取 安装说明。

通过在控制台中输入  vale -v 来验证安装。如果此命令返回 Vale 的版本号，则安装成功。

最后，创建以下文件和文件夹

├── .vale.ini
│   ├──  styles
│   │	    ├── Style guide
│   │       └── Vocab

步骤 3：配置 Vale - vale.ini

在您的仓库根目录下创建一个 vale.ini 文件。这是 Vale 的配置文件，您可以在其中定义 Vale 的行为以及要检查的文件。让我们从一个基本设置开始——您可以根据项目的需求随时添加更多配置。

StylesPath = .vale/styles
MinAlertLevel = suggestion

Vocab = word_list

[*.md]
BasedOnStyles = Meilisearch

• StylesPath 是 Vale 查找您的风格指南的位置（更多信息请参阅下一步）。该路径可以是相对于 vale.ini 文件位置的相对路径或绝对路径。

• MinAlertLevel 指定 Vale 将报告的最低警报级别。默认情况下，它设置为 warning。其他选项是 error  和 suggestion。
  错误表示您做错了什么，例如使用了多余的空格或打字错误。警告不如错误严重，但表示您应该避免的事情，例如确保您的句子不会太长。建议是做某事的推荐，这通常——但并非总是——一个好主意，例如将您的句子分成两部分而不是使用分号。
  如果规则设置为 suggestion，您将看到建议、警告和错误。如果设置为 warning，Vale 将只显示错误和警告，不显示建议。

• Vocab：这是您创建包含 accept.txt 和 reject.txt 文件的目录。这两个文件都接受单词、短语和 正则表达式。如果您的文本包含词典中不存在的单词（例如“Meilisearch”），您可以将它们添加到 accept.txt 中，Vale 就不会因为您“打错字”而对您大喊大叫。Vale 会将 reject.txt 中列出的所有出现标记为错误。当您希望作者避免使用特定词语时，这会很有用——例如，如果您正在撰写关于搜索引擎和数据库的文章，使用“indexation”可能会造成混淆。

• [*.md] 告诉 Vale 只检查 Markdown 文件。如果您想检查纯文本文件，请使用 [*.txt]。

• BasedOnStyles 指定 Vale 应使用的风格指南进行检查。

您可以指定其他设置，包括要忽略的标记和 HTML 标签，以及 Vale 应将哪些内容视为单个单词。您可以在 Vale 的文档中阅读更多关于 vale. ini 文件。

步骤 4：规则和样式文件夹

如前所述，您需要一个风格指南才能使用 Vale。然后，您将此风格指南转换为 Vale 可以理解的内容：规则。

规则使用不同的 扩展点 来执行特定任务。例如，existence 扩展点查找特定标记的存在，repetition 查找重复的标记，spelling 实现拼写检查，等等。在 Vale 中，每个规则都是一个 YAML 文件。“styles”文件夹包含构成风格指南的各个规则。

如果您不想创建自己的风格指南或需要一个起点来构建，Vale 提供了即用型风格指南，您可以将其应用于您的文档并开始检查。以下是一些帮助我们入门的风格指南：

• Google
• GitLab
• RedHat

您可以在 Vale 的 GitHub 仓库中找到更多内容。

让我们从句子长度规则开始。您的风格指南可能会这样写：“确保句子不超过 40 个词”。以下是该规则的 YAML 文件形式：

# Warning: Meilisearch.SentenceLength

# Counts words in a sentence and alerts if a sentence exceeds 40 words.

extends: occurrence
message: 'Shorter sentences improve readability (max 40 words).'
scope: sentence
link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
level: warning
max: 40
token: (w+)

此规则计算句子中的单词数，如果超过 40 个单词则发出警告。scope 设置为 sentence：这确保 Vale 不会将此规则应用于文本的其他部分，例如标题或表格。

level 设置为 warning。书面文本很复杂，Vale 会发现假阳性。没有万无一失的方法来决定何时将规则设置为建议、警告或错误。您需要边做边学，边做边决策。

我建议您定期审查您的规则，以便更新，在某些情况下，删除过时的规则。最初，Meilisearch 文档没有关于句子长度的规则。当我们添加它时，句子的最大长度是 45。现在是 40，我们计划将其降低到 35。

您还可以通过将特定规则添加到 vale.ini 中来启用或禁用风格指南中的规则。

Meilisearch.Headings = NO
Meilisearch.Spelling = NO
Meilisearch.Semicolons = NO

以上行禁用了 Meilisearch 风格指南中的标题（Heading）、拼写（Spelling）和分号（Semicolons）规则。

步骤 5：运行 Vale

现在，当您在控制台中使用以下命令来检查您的整个项目时

vale .

Vale 将根据存储在 BasedOnStyles 中的规则检查您的所有文件。如果 Vale 检测到任何问题，它将在控制台上显示建议、警告和错误。

您也可以使用以下命令检查单个文件

vale {file_path} 

步骤 6：自动化 Vale 检查

到目前为止我们讨论的所有检查都是针对您的本地文件。一旦您确信规则按预期工作，您就可以使用 Vale GitHub action 来自动化这些检查！在 Meilisearch 文档仓库中，我们将其配置为在每个拉取请求（pull request）时运行。如前所述，Vale 可能会发现假阳性（false positives）。由于您不希望因为 Vale 运行不正常而导致拉取请求（PR）被阻止，我建议您从少量规则开始，然后慢慢调整它们以避免检查失败。

结论

各位，就这些了！我希望我能帮助您开始使用 Vale（以及风格指南）。这是一个快速概述，旨在向您介绍 Vale 的功能。根据您的需求进行调整需要时间，以及许多、*许多*次迭代。

配置完成后，Vale 可以自动化审阅过程的一部分，让您能够专注于计算机不擅长的文本部分。至少目前是这样。

哦，如果您好奇，请查看 我们在 GitHub 上的风格指南，看看我们是如何使用 Vale 的！