使用 Vale 进行散文检查

写作是一个耗时的过程。根据作者和评审过程的不同，内容准备发布可能需要一段时间。无论您是个人作者还是大型团队，散文校对工具都可以帮助确保一致的语气和风格。

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

散文校对工具还可以为创建和实施编辑样式指南提供框架。这有助于评审过程，因为您现在可以专注于评审内容本身，而不是指出拼写错误和偏好的使用模式。这在 Meilisearch 这样的开源项目中尤其重要，在这些项目中，您有许多不熟悉您的样式指南的贡献者。

什么是 Vale？

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

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

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

我从哪里开始？

尽管 Vale 的设置可能看起来令人望而生畏，但如果您从小处着手并保持简单，它可能会相当简单。在这篇文章中，我们将介绍如何在项目中像Meilisearch 的文档一样使用 Vale。

步骤 1：样式指南

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

如果您没有内部样式指南，您可以查看谷歌的或微软的来帮助您入门。随着时间的推移，您会记住大部分规则，但有时可能会忽略错误，甚至完全忘记规则。我们只是人类。

这就是 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 提供了即用型样式指南，您可以将其应用于文档并开始进行校对。以下是一些帮助我们入门的样式指南

• 谷歌
• GitLab
• 红帽

您可以在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 样式指南中的标题、拼写和分号规则。

步骤 5：运行 Vale

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

vale .

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

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

vale {file_path} 

步骤 6：自动化 Vale 检查

我们目前讨论的所有检查都针对您的本地文件。一旦您确信这些规则按预期工作，您就可以使用 Vale GitHub action 自动化这些检查！在 Meilisearch 文档存储库中，我们将其配置为在每次拉取请求时运行。如前所述，Vale 可能会发现误报。由于您不希望由于 Vale 未按预期工作而导致 PR 被阻塞，我建议从几个规则开始，并慢慢调整它们以避免检查失败。

结论

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

一旦配置好，Vale 就可以自动化审查过程的一部分，让您可以专注于文本中计算机不太擅长的部分。至少目前是这样。

哦，如果您好奇的话，请查看我们 GitHub 上的样式指南，看看我们如何使用 Vale！