textlintで日本語レビュー

Posted at 2024-09-08

textlintについては、既に多くの方が記事にしていますが、個人的な学習記録として、この度、記事化する事にしました。

正しい日本語とは？

システム開発で、ドキュメントを書く際に、日本語の文法、使い方に関する指摘・レビューが入ることがあります。

明らかな誤字脱字ならばともかく、人によっては、これは本当に間違いなのか？と疑問に思うことがあります。

正しい日本語について、機械的に判定する仕組みがあると便利ですね。

textlintを導入することで、そのような悩みを解決することができます。

導入手順および使い方は、公式サイトに詳しく書かれています。

textlintは、開発中の様々なシーンで利用することができます。

①検証したいタイミングでコマンドを打つ

ターミナルから、以下のコマンドを実行すると、いつでも日本語の検証を実行することができます。

npx textlint hoge/**/*.md

②CIに組み込む

GitHub Actions で上記のコマンドを実行すれば、Git Push時に必ず検証させることができます。

③文章を書きながら、検証させる。

VSCodeのプラグインを導入することで、いちいちコマンドを打たなくても、検証されるようになります。

こちらの記事が参考になると思います。

以下、私がお勧めする、使い方・設定を紹介します。

textlintの設定は、名前が「.textlintrc」から始まるファイルに定義します。
JSON, YAML, JSで記述可能ですが、シンプルで、かつコメントが残せるYAMLの採用をお勧めします。

textlintは、検証する時に使用するルールを細かくカスタマイズできます。

それゆえに、最初は何を適用すべきか迷いますが、まずは以下のルールを導入することをお勧めします。

こちらは、厳密にはルールのプリセットになっていて、複数の検証ルールが入っています。

それぞれのルールをオフにしたり、細かくカスタマイズできるので、便利です。

検証で引っかかった時に、errorではなく、warning扱いにすることができます。
warningの場合は、

echo $?

の実行結果が0(True)、つまり、textlintの実行自体は成功になるため、CIを止めることなく、先に進ませることができます。