使用 Vale 进行散文风格检查

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

与代码检查器类似，散文风格检查器会自动检查您的文本中的错误。与语法检查器（突出显示语法规则的违反情况）不同，散文风格检查器侧重于如何通过解决常见的用法问题（如多余的空格、重复的单词、过度使用术语、性别歧视语言和不正确的 capitalization）来改进您的文本。

散文风格检查器还可以为创建和执行编辑风格指南提供框架。这有助于审核流程，因为您现在可以专注于审核内容本身，而不是指出错别字和首选用法模式。当在像 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：规则和 styles 文件夹

正如我之前提到的，您需要一个风格指南才能使用 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 文档存储库中，我们将其配置为为每个拉取请求运行。如前所述，Vale 可能会发现误报。由于您不希望 PR 因为 Vale 未按预期工作而被阻止，因此我建议从一些规则开始，并缓慢调整它们以避免检查失败。

结论

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

配置完成后，Vale 可以自动化审核过程的某些部分，并让您专注于计算机不太擅长的文本部分。至少目前还没有。

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