みなさん、こんにちは。AWS CLI が好きな AWSサポート課の市野です。
今日は、AWS の特定分野の話題ではなくオープンソースの文書チェックツールである textlint を使ってみた話です。
そもそも textlint とは
文章の校正や表記ゆれのチェックを行うことができるオープンソースのツールです。
句読点や助詞の重複など文章のタイプに合わせたルールが多数用意されており、独自のルールを作成することも可能となっています。
余談
せっかくなので「強化された CLI エージェントとして」2025 年 3 月 6 日 の AWS ブログで発表された Amazon Q Developer for CLI にも聞いてみました。
完全に AWS と関係ない話題でしたが知っているようですね。
しかも、技術ブログの下書きをしていたディレクトリで q chat を実施したので、カレントディレクトリ配下の内包物の考慮の跡が伺えます。
使ってみる
インストール
前提として Node.js の動作環境は整っているものとします。
textlint のインストール
% npm install textlint
ルールのインストール
textlint のルールは自作もできますが、すでに公開されているルールやいくつかのルールを束ねたプリセットを導入可能です。 さらに、日本語文書に特化したルールを扱うコミュニティとして textlint-ja という GitHub Organization も存在しています。
今回は、該当の GitHub Organization から以下のルール（プリセット）を導入してみます。
- textlint-rule-preset-japanese：日本語向けの一般的な文書で利用するためのルール集
- textlint-rule-preset-ja-technical-writing：技術文書向けのルールプリセット
% npm install textlint-rule-preset-japanese \ textlint-rule-preset-ja-technical-writing
単体のルールでの校正
インストール済みのルールのうち単体のルールを利用し校正する場合は npx textlint --rule <rule名> <文書ファイル> の要領で実施可能です。
ここでは、先日私が書いた AWS マネジメントコンソールで同時に複数の AWS アカウントへログインできるようになりました の元原稿を校正してみます。
私は元々 Markdown でブログ原稿を書いているので、こういう時にツールが楽に適用できていいですね。
まずは、textlint-rule-preset-japanese のルールだけを使って校正してみます。
% npx textlint --rule textlint-rule-preset-japanese docs/blog/posts/sign-in-for-multiple-AWS-accounts.md /Users/xxx/xxx/blog/docs/blog/posts/sign-in-for-multiple-AWS-accounts.md 26:413 error Line 26 sentence length(126) exceeds the maximum sentence length of 100. Over 26 characters japanese/sentence-length 30:548 error Line 30 sentence length(134) exceeds the maximum sentence length of 100. Over 34 characters japanese/sentence-length 32:57 error 一文に二回以上利用されている助詞 "が" がみつかりました。 次の助詞が連続しているため、文を読みにくくしています。 - "が" - "が" 同じ助詞を連続して利用しない、文の中で順番を入れ替える、文を分割するなどを検討してください。 japanese/no-doubled-joshi 34:932 error Line 34 sentence length(152) exceeds the maximum sentence length of 100. Over 52 characters japanese/sentence-length 36:1235 error Line 36 sentence length(126) exceeds the maximum sentence length of 100. Over 26 characters japanese/sentence-length 44:2135 error Line 44 sentence length(164) exceeds the maximum sentence length of 100. Over 64 characters japanese/sentence-length 51:2521 error Line 51 sentence length(136) exceeds the maximum sentence length of 100. Over 36 characters japanese/sentence-length 59:46 error 一文に二回以上利用されている助詞 "でも" がみつかりました。 次の助詞が連続しているため、文を読みにくくしています。 - "でも" - "でも" 同じ助詞を連続して利用しない、文の中で順番を入れ替える、文を分割するなどを検討してください。 japanese/no-doubled-joshi 61:3080 error Line 61 sentence length(106) exceeds the maximum sentence length of 100. Over 6 characters japanese/sentence-length 67:3337 error Line 67 sentence length(187) exceeds the maximum sentence length of 100. Over 87 characters japanese/sentence-length 69:3524 error Line 69 sentence length(138) exceeds the maximum sentence length of 100. Over 38 characters japanese/sentence-length 71:3764 error Line 71 sentence length(112) exceeds the maximum sentence length of 100. Over 12 characters japanese/sentence-length 71:3978 error Line 71 sentence length(118) exceeds the maximum sentence length of 100. Over 18 characters japanese/sentence-length 81:4380 error Line 81 sentence length(215) exceeds the maximum sentence length of 100. Over 115 characters japanese/sentence-length 94:5064 error Line 94 sentence length(126) exceeds the maximum sentence length of 100. Over 26 characters japanese/sentence-length ✖ 15 problems (15 errors, 0 warnings)
なんだかんだと 15 ヶ所指摘されました。
複数ルールでの総合的な校正
textlint 本体の Usage を確認すると npx textlint --init コマンドでインストールされているルールから .textlintrc.json を作成されると解説があります。
.textlintrc.json の作成と確認
% npx textlint --init
.textlintrc.json is created.
% cat .textlintrc.json
{
"plugins": {},
"filters": {},
"rules": {
"preset-ja-technical-writing": true,
"preset-japanese": true
}
}
上記の cat の結果の通り、インストールしたルールから .textlintrc.json が作成されました。
.textlintrc.json がカレントディレクトリに存在している場合 --rule オプションの有無に関わらず、.textlintrc.json で true となっているルールに基づいた校正をします。
% npx textlint docs/blog/posts/sign-in-for-multiple-AWS-accounts.md
/Users/xxx/xxx/blog/docs/blog/posts/sign-in-for-multiple-AWS-accounts.md
13:42 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase
26:413 error Line 26 sentence length(126) exceeds the maximum sentence length of 100.
Over 26 characters ja-technical-writing/sentence-length
30:135 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
30:548 error Line 30 sentence length(134) exceeds the maximum sentence length of 100.
Over 34 characters ja-technical-writing/sentence-length
32:57 error 一文に二回以上利用されている助詞 "が" がみつかりました。
次の助詞が連続しているため、文を読みにくくしています。
- "が"
- "が"
同じ助詞を連続して利用しない、文の中で順番を入れ替える、文を分割するなどを検討してください。
ja-technical-writing/no-doubled-joshi
32:62 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
34:155 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
34:932 error Line 34 sentence length(152) exceeds the maximum sentence length of 100.
Over 52 characters ja-technical-writing/sentence-length
35:53 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
36:127 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
36:1235 error Line 36 sentence length(126) exceeds the maximum sentence length of 100.
Over 26 characters ja-technical-writing/sentence-length
37:63 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
38:126 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
39:70 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
40:111 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
42:74 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
43:30 error 【dict5】 "ロールを行う"は冗長な表現です。"ロールする"など簡潔な表現にすると文章が明瞭になります。
解説: https://github.com/textlint-ja/textlint-rule-ja-no-redundant-expression#dict5 ja-technical-writing/ja-no-redundant-expression
43:121 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
44:165 error 箇条書き: "である"調 でなければなりません
=> "である"調 であるべき箇所に、次の "ですます"調 の箇所があります: "ます。"
Total:
である : 0
ですます: 20
ja-technical-writing/no-mix-dearu-desumasu
44:2135 error Line 44 sentence length(164) exceeds the maximum sentence length of 100.
Over 64 characters ja-technical-writing/sentence-length
51:2521 error Line 51 sentence length(136) exceeds the maximum sentence length of 100.
Over 36 characters ja-technical-writing/sentence-length
59:46 error 一文に二回以上利用されている助詞 "でも" がみつかりました。
次の助詞が連続しているため、文を読みにくくしています。
- "でも"
- "でも"
同じ助詞を連続して利用しない、文の中で順番を入れ替える、文を分割するなどを検討してください。
ja-technical-writing/no-doubled-joshi
61:3080 error Line 61 sentence length(106) exceeds the maximum sentence length of 100.
Over 6 characters ja-technical-writing/sentence-length
67:3337 error Line 67 sentence length(187) exceeds the maximum sentence length of 100.
Over 87 characters ja-technical-writing/sentence-length
69:233 error 弱い表現: "かも" が使われています。 ja-technical-writing/ja-no-weak-phrase
69:3524 error Line 69 sentence length(138) exceeds the maximum sentence length of 100.
Over 38 characters ja-technical-writing/sentence-length
71:3764 error Line 71 sentence length(112) exceeds the maximum sentence length of 100.
Over 12 characters ja-technical-writing/sentence-length
71:3978 error Line 71 sentence length(118) exceeds the maximum sentence length of 100.
Over 18 characters ja-technical-writing/sentence-length
75:10 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark
81:4380 error Line 81 sentence length(215) exceeds the maximum sentence length of 100.
Over 115 characters ja-technical-writing/sentence-length
94:5064 error Line 94 sentence length(126) exceeds the maximum sentence length of 100.
Over 26 characters ja-technical-writing/sentence-length
✖ 31 problems (31 errors, 0 warnings)
textlint-rule-preset-japanese だけの校正にはなかった、以下のような指摘が加わりました。
13:42 error 弱い表現: "思います" が使われています。
30:135 error 箇条書き: "である"調 でなければなりません
43:30 error 【dict5】 "ロールを行う"は冗長な表現です。"ロールする"など簡潔な表現にすると文章が明瞭になります。
結果の末尾にある ja-technical-writing/ja-no-weak-phrase などの記述から、どのルールで判定されたものかが判別できます。
プリセットに含まれる場合はどのプリセットに入っているかも判別可能です。
結果として、技術文書として弱い表現となる "思います" の使用や、箇条書きで "である"調 が使われていない点の指摘が加わっています。
また、助詞の繰り返しや、一行の長さも判定してくれますし、今回はありませんでしたが文中に「、」が 4 つ以上出現した場合にも注意が促されます。
そのような場合は 2 文に分けるなどの文書構成の再検討が望ましいと考えられます。
おまけ
今回検証から外しましたが、VS Code のエクステンション vscode-textlint を利用することで、VS Code での記述中に自動での校正も可能です。
npx コマンドでの確認の場合、文書を作成・保存してから適宜コマンドを実行して判定する必要がありますが、VS Code エクステンションでの場合は書きながら判定してもらうことが可能です。
技術文書を書く頻度が高い方は導入を検討してみても良いかもしれません。
おわりに
私自身がテクニカルサポートという職種に従事していることもあり、なるべくわかりやすい文章を書こうと心がけてはいました。
ただ、ちょっと一行が長くなりすぎかななど、書きながら感覚で調整していた部分もあり、先日書いたブログでも 31 箇所の指摘があることに少々びっくりしました。
そのため、これまでにご案内をしてきた問い合わせチケットでも、冗長な書き方や意図が伝わりにくい表現をしていたかもしれないと反省しています。
文面の内容の正確さは自身で担保しつつ、より読みやすく誤解の少ない文章の組み立てに、このようなツールの利用は有用だと感じました。
この記事が、何らかの技術文書や日本語文書を書く方のお役に立てば幸いです。
ではまた。
市野 和明 (記事一覧)
マネージドサービス部・テクニカルサポート課
お客様から寄せられたご質問や技術検証を通じて得られた気づきを投稿していきます。
情シスだった前職までの経験で、UI がコロコロ変わる AWS においては GUI で手順を残していると画面構成が変わってしまって後々まごつくことが多かった経験から、極力変わりにくい AWS CLI での記事が多めです。
X（Twitter）：@kazzpapa3（AWS Community Builder）
