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

## Vale とは

https://vale.sh/

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

## 環境

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

## Vale インストール

```sh
brew install vale
mkdir vale_example
cd vale_example
```

## 設定ファイル作成

[Config Generator](https://vale.sh/generator/) を活用するなどして設定ファイルを作成します。今回は [Microsoft スタイルガイド](https://vale.sh/hub/microsoft/)と [write-good](https://vale.sh/hub/write-good/) の Vale styles を導入してみます。なお、その他の Vale styles は [Package Hub](https://vale.sh/hub/) で確認できます。

```sh
vi .vale.ini
```

```ini:.vale.ini
StylesPath = styles

MinAlertLevel = suggestion
Vocab = Base

Packages = Microsoft, write-good

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

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

## Vale styles インストール

```sh
vale sync
```

```console
$ ls styles
Microsoft  Vocab      write-good
```

## 許可単語リスト作成

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

```sh
vi styles/Vocab/Base/accept.txt
```

```txt:styles/Vocab/Base/accept.txt
fuga
hoge
```

## .gitignore 作成

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

```sh
vi .gitignore
```

```ignore:.gitignore
/styles/Microsoft/
/styles/write-good/

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

## ドキュメント作成

```sh
mkdir docs
vi docs/index.md
```

```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 による校正実行

```console
$ 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](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server)
- GitHub Actions：[Vale Linter · Actions · GitHub Marketplace](https://github.com/marketplace/actions/vale-linter)
  - この Vale 公式の action は少し癖がある気がするので、具体例として [Base Template Repository](https://github.com/haru52/base_template/blob/v1.18.0/.github/workflows/test.yml#L22-L31) などをご参照いただくと良いかも知れません
- その他：[Vale 公式ドキュメント](https://vale.sh/docs/integrations/guide/) の `INTEGRATIONS`

## サンプルリポジトリ

https://github.com/haru52/vale_example

## 参考

- [Documentation testing | GitLab](https://docs.gitlab.com/ee/development/documentation/testing.html)