Vale による英語ドキュメント校正入門 #Markdown

Vale とは

Vale は Markdown などの構文を理解した上で英文のスペルとスタイルを校正するツールです
似たツールとしては textlint が挙げられます
textlint は日本語の校正には強いものの、英文のルールやプリセットはそこまで充実していない印象があります
Vale 開発者の主張によると、Vale は textlint などの競合ツールより高速であることを売りにしているようです。ちなみに Vale の実装言語は Go です
Vale には CLI 版と Server 版の 2 種類あります
本記事は Vale CLI を対象にしています
Vale は英文のスペルとスタイルをチェックしますが、原則、文法はチェックしません
文法もカバーしたい場合は、例えば Grammarly など他のツールを併用する必要があります

環境

macOS v12.4 (Monterey)
Homebrew v3.5.2
Vale CLI v2.18.0

Vale インストール

brew install vale
mkdir vale_example
cd vale_example

設定ファイル作成

Config Generator を活用するなどして設定ファイルを作成します。今回は Microsoft スタイルガイドと write-good の Vale styles を導入してみます。なお、その他の Vale styles は Package Hub で確認できます。

vi .vale.ini

.vale.ini

StylesPath = styles

MinAlertLevel = suggestion
Vocab = Base

Packages = Microsoft, write-good

[*]
BasedOnStyles = Vale, Microsoft, write-good

BasedOnStyles に指定している Vale という値は、Vale デフォルトのスペルチェック機能などを有効にする意味があります。

Vale styles インストール

vale sync

$ ls styles
Microsoft  Vocab      write-good

許可単語リスト作成

Vale にはデフォルトで英単語のスペルチェック機能が備わっています。これは便利な一方、特殊な固有名詞などが引っ掛かってしまうので、スペルチェックでエラーにしたくない英単語のリストを作ってみます。

vi styles/Vocab/Base/accept.txt

styles/Vocab/Base/accept.txt

fuga
hoge

.gitignore 作成

Microsoft スタイルガイドの Vale style などはプロジェクト固有のファイルではなく、そのままダウンロード（コピー）してきたものを配置しているだけです。よって、これらは Git 管理対象外にするのが良いでしょう。一方、/styles/Vocab/Base/ 配下のファイルはプロジェクト固有の設定を書き込むためのものなので Git の管理下に置きます。

vi .gitignore

.gitignore

/styles/Microsoft/
/styles/write-good/

# 以下の指定方法の方が良さそうなのですが、自分の環境ではうまく機能しないので調査中です
# /styles/*
# !/styles/Vocab/Base/

ドキュメント作成

mkdir docs
vi docs/index.md

docs/index.md

# Example

- This misspeling and passive voice will be detected by Vale
- Vale cannot fix errors and warnings automatically
- Vale allows fuga and hoge words in this project

<!-- Vale の全チェックを無効化する ignore コメント -->
<!-- vale off -->
This misspeling and passive voice won't be detected!
<!-- 再度有効化 -->
<!-- vale on -->

<!-- Vale の特定のルールのみを無効化する ignore コメント -->
<!-- vale Vale.Spelling = NO -->
This passive voice will be detected but not this misspeling!
<!-- vale Vale.Spelling = YES -->

Vale による校正実行

$ vale docs

 docs/index.md
 3:8    error       Did you really mean             Vale.Spelling          
                    'misspeling'?                                          
 3:42   suggestion  Try to avoid using 'be'.        write-good.E-Prime     
 3:42   suggestion  'be detected' looks like        Microsoft.Passive      
                    passive voice.                                         
 3:42   warning     'be detected' may be passive    write-good.Passive     
                    voice. Use active voice if you                         
                    can.                                                   
 4:8    error       Use 'can't' instead of          Microsoft.Contractions 
                    'cannot'.                                              
 5:8    suggestion  Verify your use of 'allows'     Microsoft.Vocab        
                    with the A-Z word list.                                
 15:25  suggestion  Try to avoid using 'be'.        write-good.E-Prime     
 15:25  suggestion  'be detected' looks like        Microsoft.Passive      
                    passive voice.                                         
 15:25  warning     'be detected' may be passive    write-good.Passive     
                    voice. Use active voice if you                         
                    can.                                                   

✖ 2 errors, 2 warnings and 5 suggestions in 1 file.

こんな感じで校正結果を確認できます。なお、残念ながら（少なくとも現バージョンの）Vale は textlint のようにエラー等を自動修正する機能を持っていません。そのため、エラー等は全て手動で修正する必要があります。

他ツールとの連携

VS Code：Vale - Visual Studio Marketplace
GitHub Actions：Vale Linter · Actions · GitHub Marketplace
- この Vale 公式の action は少し癖がある気がするので、具体例として Base Template Repository などをご参照いただくと良いかも知れません
その他：Vale 公式ドキュメントの INTEGRATIONS

サンプルリポジトリ

参考

Documentation testing | GitLab