使用 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 中列出的所有出現次數標記為錯誤。當您希望作者避免使用特定單字時，這可能會很有用—例如，如果您正在撰寫關於搜尋引擎和資料庫的文章，使用「索引編制」可能會令人困惑。

• [*.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 風格指南中的「標題」、「拼寫」和「分號」規則。

步驟 5：執行 Vale

現在，當你在主控台中使用以下指令來檢查整個專案時：

vale .

Vale 會根據 BasedOnStyles 中儲存的規則檢查你所有的檔案。如果 Vale 偵測到任何問題，它會在主控台上顯示建議、警告和錯誤。

你也可以使用以下指令來檢查個別檔案：

vale {file_path} 

步驟 6：自動化 Vale 檢查

到目前為止，我們討論的所有檢查都是針對你的本機檔案。一旦你確認這些規則運作正常，你可以使用 Vale GitHub Action 來自動化這些檢查！在 Meilisearch 文件儲存庫中，我們已將其設定為針對每個提取請求執行。如前所述，Vale 可能會發現誤判。由於你不會希望因為 Vale 無法正常運作而導致 PR 被阻擋，我建議先從幾個規則開始，然後慢慢調整它們，以避免檢查失敗。

結論

各位，就這樣！我希望我能夠幫助你開始使用 Vale（以及風格指南）。這是一個快速概述，向你介紹 Vale 的功能。根據你的需求進行調整需要時間和許多許多次的迭代。

一旦設定完成，Vale 可以自動化審閱流程的部分環節，讓你專注於電腦不擅長的文字部分。至少目前還不擅長。

喔，如果你有興趣，可以查看 我們在 GitHub 上的風格指南，了解我們如何使用 Vale！