如何借助Vale减少开源社区文档中的负面和偏见语言

整理 | 西狩xs 校对 | 山河已无恙

出品 | CSDN云原生

声明：本文出自CNCF，由技术作家Chris Ward在Chronosphere博客上发表。CSDN将文章翻译成中文，分享给大家。

在许多开源社区中，围绕什么语言代表了消极、偏见和多样性的讨论不绝于耳，为此还经常引发激烈的、固执己见的争论。抛开这些讨论的内容不谈，假设你已经决定要在社区中增加、减少或更改一些语言，你会如何执行和跟踪这些变化？

这篇文章源于2021年我在All Things Open的一次演讲，主要分享了如何通过开源工具Vale来检查语言文本是否符合提前定义的规则和风格。

语言示例

总的来说，要识别的语言类型可能包括以下内容。

屈尊俯就（Patronizing）：因为不理解作者所说的一些显而易见的事情，而让读者自己感到愚蠢或无知的语言。
粗鲁（Rude）：明确使用冒犯性词语或贬低性措辞的语言。
过度消极（Overly negative）：这种语言会使读者感到某项任务难以完成，或者让他们厌倦继续阅读。
有偏见的（Biased）：不必要地使用对一个群体有偏好或偏见的语言。
过时的（Out-dated）：使用被广泛认为是过时的或不恰当的语言。
无用（Unhelpful）：对文本没有任何增色的语言，或者使文本变得更糟——变为上述其他类型的语言之一。

Linting 简介

您可能以前就使用过拼写检查器，因为很多系统或应用程序都有这项功能。而现在，越来越多的工具添加了语法检查器，甚至开始有些工具提供了样式检查器。如果某个工具允许你自定义样式检查器，那么你可以使用它来查找某些对你很重要的问题，包括消极和有偏见的语言。

其中一些工具使用自然语言处理和机器学习来分析文本并提出建议，还有些人则使用程序员熟悉的linting概念进行文本查找（代码基本上就是文本）。

引用Wikipedia（维基百科）的话，linter是：

“……一种用于标记编程错误、缺陷、样式错误和可疑结构的静态代码分析工具。”

这听起来很适合这项任务，毕竟，文本的样式问题和潜在问题可能并不一定是错误的，但值得我们关注。

Lint文本工具（虽然并非所有工具实际上都是 linters）包括这些：

Grammarly
商业内置（谷歌文档等）
Acrolinx
Text lint
“一次性”工具（Alex、Write good、Job lint等）
LanguageTool
Vale （我的选择）

Vale简介

Vale是一个你可以自己托管、运行和配置的开源工具。使用这个工具虽然可能意味着更加复杂的设置，但也提供了很大的灵活性和对内容访问权限的控制。Vale可以与开发人员和技术作者经常使用的文本编辑器集成，你可以从命令行运行它，这意味着你可以让 Vale 成为任何针对内容的自动化测试过程的一部分。借助目前收费30美元的Vale Server，你还可以将Vale与少部分开发人员关注的工具一起使用，如Google Docs或网页上的文本字段。

补充一点，Vale已经实现了前面提到的Write good、Alex、Job lint、LanguageTool 等工具的功能。

安装

由于有多种安装和设置的选择，下面将主要介绍Vale与Visual Studio Code在macOS上的运行。

我们可以使用Homebrew安装：

brew install vale

或从Vale 网站下载预构建的二进制文件。

配置

为了实现检查文本的功能，Vale 需要两个主要组件。

一组定义检查文本所依据的“规则”的样式集合。Vale有许多预先构建的样式，同时支持自定义样式。
一个.vale.ini 配置文件，该文件定义了样式的位置以及要启用的样式。

例如：下面的配置设置了一个通往样式目录的路径，并覆盖了某些样式中的一些规则。

StylesPath = vale-styles[*]
write-good.Passive = warning
write-good.TooWordy = warning
write-good.So = warning
write-good.Weasel = warning
write-good.ThereIs = suggestion
Openly.UnclearAntecedent = warning
Openly.FutureTense = warning
Openly.Spelling = error
Openly.Quotes = warning
Openly.Readability = warning

Vale首先会在你正在linting的文件的相同目录下寻找配置文件。如果找不到，它会在文件树中向上搜索6级，直到找到一个；如果还没有，那么就在当前用户的主文件夹中查找一个。这意味着你可以拥有全局配置以及单个项目的配置。

运行Vale

在不安装任何集成选项的情况下，可以使用以下命令从命令行运行 Vale：


vale {file_name}

它会将检查结果逐行输出到控制台，其中包含行号、违反的规则和违反的严重程度等详细信息。

将Vale与其他工具一起使用

通过命令行运行Vale非常适合在完成编写时检查文本，但不适合在编写过程中检查文本。

幸运的是，大多数流行的文本编辑器都有可用的扩展，包括Sublime text、Emacs、Visual Studio Code和Vim。Vale有一个名为Vale Server的商业版本，它支持Google Docs和Chrome等，并且很快就会免费和开源。

这些扩展以更直观的格式内嵌在文本中来展示错误，有时还会提供修复建议。

样式和规则

Vale真正强大的是它的样式和规则，这就是Vale在识别问题语言方面的作用。样式由一组YAML文件组成，这些文件是独立的规则，并使用其中一个“拓展点”。

YAML文件由正则表达式（RegEx）和一些配置组成，具体取决于配置的规则。RegEx功能强大但比较复杂，虽然Vale试图将这种复杂性抽象出来，使其更具备“用户友好性”，但仍需要花费时间去理解。值得庆幸的是，有许多现有规则可供参考。

为了展示一些扩展点是如何工作的，我们可以为这篇文章在GitHub仓库中找到一系列预先构建好的样式。

说明一下，为了突出显示问题文本中的实例，文章中需要展示一些有问题的文本。这仅仅是为了达到解释说明的目的。

【性别歧视语言】

仔细思考以下文本：

以前有做女警察、女售货员或女服务员的经验。

对此示例，你可能想要建议性别中立的替代方案。这就是“subsitution”扩展点所处理的，当它遇到左边的文本时就会提示右边的文本：

另一个例子是通过使用“existence”扩展点来突出显示“guys”，当 Vale 在文本中找到一个标记时，该扩展点就会触发。

【居高临下的语言】

仔细思考以下文本：

每个人都知道我们的软件很简单就能理解，而且只是一个数据库。任何人都可以很容易地理解它。

同样，这是一个“existence”扩展点的示例，但这次突出显示了“每个人都知道”、“简单”和“容易”等词。

下一步计划

为Vale配置规则和样式需要一些时间，但在其他人已经创建的基础上继续构建配置能够让你走得更远。推荐一个有助于入门的GitHub仓库，同时Vale相关的社区也有大量资料。

Vale其实还可以做很多事情，本文仅作抛砖引玉，谢谢收看。

聚焦云原生新技术、新实践，帮助开发者群体赢在开发范式转移的新时代。欢迎关注CSDN云原生微信公众号～