textlintを使った表記揺れチェック ことはじめ

Transcript

1. 1 / 52 textlintを使った表記揺れチェック ことはじめ サイボウズ株式会社 ぴよ
2. 2 / 52 テクニカルライターの悩みごと ドキュメントの一貫性を保つのは難しい 表記揺れをしてしまう 2要素認証 or 二要素認証 or 2段階認証 スタイルガイドに沿って書かれていない 「〜することができる」など、冗長な表現を避ける 本質的な内容をレビューしてほしいけど、その手前のことを指摘されてしまう textlintを使うことで、これらの悩みを解決できる 2
3. 3 / 52 自己紹介と宣伝 3
4. 4 / 52 自己紹介 piyo サイボウズ株式会社 テクニカルライター サイボウズ製品のヘルプ 製品のUI文言 ヘルプサイトの配信基盤のメンテナンス X: @_chick_p 4
5. 5 / 52 サイボウズ株式会社 グループウェアの開発、販売 中小企業向けグループウェア 80,000社 業務アプリ作成プラットフォーム 36,000社 大企業向けグループウェア 7,800社 メール共有システム 15,000社 2024年8月末時点 5
6. 6 / 52 リレーブログを開催中 サイボウズのテクニカルライターとローカライズ担当が、リレー形式でブログを 書いています https://blog.cybozu.io/entry/2024/08/22/111500 サイボウズ　リレーブログ　テクニカルライター 検索 6
7. 7 / 52 textlintを使って、ドキュメントをチェックしよう 7
8. 8 / 52 今日の話のターゲットとゴール ターゲット textlintを知らない人 名前は聞いたことあるくらいの人 ゴール 自分やチームメンバーが書いたドキュメントを、ツールを使ってチェックできる ようになる 8
9. 9 / 52 textlint テキスト校正のためのツール textlintのルールを組み合わせて、ドキュメントをチェックできる https://textlint.github.io/ textlintのルール チェックする内容を定義したプログラムのこと 例 「冗長な"〜することができる"をチェックする」ルール 「文末に句点をつける」ルール 9
10. 10 / 52 textlint導入までの道のり Step1：textlintをセットアップする Step2：textlintでドキュメントをチェックする Step3：ルールを追加する Step4：prhルールを活用する Step5：行単位でtextlintのルールを無効にする 10
11. 11 / 52 Step1: textlintをセットアップする 11
12. 12 / 52 textlintを実行するために必要なもの Node.js textlint textlintの本体プログラム textlintのルールプログラム textlintの設定ファイル 12
13. 13 / 52 Node.jsをインストールする（1/4） Node.jsはJavaScriptという言語で書かれたプログラムを実行するための環境 textlintはJavaScriptで書かれているため、Node.jsが必要 13
14. 14 / 52 Node.jsをインストールする（2/4） 1. 公式サイトにアクセスし、[Download Node.js(LTS)]をクリックする 公式サイト：https://nodejs.org/ 2. インストーラーをダブルクリックし、画面の指示に従ってインストールする 14
15. 15 / 52 Node.jsをインストールする（3/4） 3. ターミナルソフトを開く Windows 画面左下の検索ボックスで「Terminal」と検索し、「Windows Terminal」 または「コマンドプロンプト」をクリック macOS 画面右上の虫眼鏡アイコンから「ターミナル」と検索して、「ターミナル」 をクリック 15
16. 16 / 52 Node.jsをインストールする（4/4） 4. node -—version を入力してEnterキーを入力し、バージョン番号が表示さ れることを確認する node --version # 実行結果 v20.17.0 Node.jsのバージョンを確認したときの画面 16
17. 17 / 52 textlintの本体をインストールする 1. 作業ディレクトリを作成する（例：「playground-textlint」 ） 2. 作業ディレクトリにcd コマンドで移動する # 「playground-textlint」ディレクトリに移動 cd playground-textlint 3. textlint本体をインストールするコマンドを入力し、Enterキーを押す # textlintの本体をインストール npm install textlint 実行に必要なファイルが生成される 17
18. 18 / 52 textlintのルールをインストールする 先ほどと同じディレクトリ内で、ルールをインストールするコマンドを実行する 例として、「半角カナの利用を禁止する」ルールをインストールする # 「半角カナの利用を禁止する」ルールをインストールする npm install textlint-rule-no-hankaku-kana 18
19. 19 / 52 ルールの設定ファイルを作る ルールの設定ファイルを生成するコマンドを実行する インストール済みのルールが有効になった、ルールの設定ファイルが生成される .textlintrc.json # ルールの設定ファイルを生成するコマンド npx textlint --init { "plugins": {}, "filters": {}, "rules": { "no-hankaku-kana": true } } 19
20. 20 / 52 Step2: textlintでドキュメントをチェックする 20
21. 21 / 52 チェックするドキュメントを準備する 1. テキストエディタで、次の内容を入力する 設定を有効にすると、ﾍｯﾀﾞの[二要素認証]をクリックすることができます。 2. textlintをインストールしたディレクトリの下に、ファイルを保存する 例として、ファイル名を「sample.txt」にする 文字コードは「UTF-8」にする 21
22. 22 / 52 textlintを実行する ターミナルソフトでnpx textlint ファイル名 を実行する ルールに違反している文があると、実行結果にエラーが表示される npx textlint sample.txt # 実行結果 /Users/chick-p/Desktop/playground-textlint/sample.txt 1:11 ✓ error Disallow to use 半角カタカナ: "ﾍｯﾀﾞ" no-hankaku-kana ✖ 1 problem (1 error, 0 warnings) ✓ 1 fixable problem. Try to run: $ textlint --fix [file] 22
23. 23 / 52 エラーを自動修正する ✓がついているエラーは、textlintを実行するときに--fix オプションをつける と自動で修正できる ファイルの中身を確認すると、全角カタカナに修正されている --fix オプションに対応しているかは、ルールによって異なる # --fixオプションをつけると、自動で修正できる npx textlint sample.txt --fix # 実行結果 /Users/chick-p/Desktop/playground-textlint/sample.txt 1:11 ✓ error Disallow to use 半角カタカナ: "ﾍｯﾀﾞ" no-hankaku-kana ✔ Fixed 1 problem 23
24. 24 / 52 Step3: ルールを追加する 24
25. 25 / 52 どんなルールを使えばいいの？ npmで「textlint-rule」で検索して、ルールを探す https://www.npmjs.com/search?q=textlint-rule 2024年9月時点で300弱のルールが、npmに公開されている この中から、会社のスタイルガイドに合うルールを選択する 25
26. 26 / 52 ルールの例 たとえば、スライドの最初の方で挙げた例を、チェックできるルール 「冗長な”〜することができる”をチェックする」ルール textlint-rule-ja-no-redundant-expression 「文末に句点をつける」ルール textlint-rule-ja-no-mixed-period 26
27. 27 / 52 さらにルールを追加する（1/2） 「"冗長な”〜することができる”をチェックする」ルールを追加する 「.textlintrc.json」をテキストエディタで開いて、rules プロパティに追記する .textlintrc.json # 「"冗長な”〜することができる”をチェックする」ルールをインストール npm install textlint-rule-ja-no-redundant-expression { // 省略 "rules": { "no-hankaku-kana": true, "ja-no-redundant-expression": true } } 27
28. 28 / 52 さらにルールを追加する（2/2） ルールの追加方法や設定内容は、各ルールのドキュメントを参照する Ref. https://www.npmjs.com/package/textlint-rule-ja-no-redundant- expression/v/1.0.2?activeTab=readme 28
29. 29 / 52 追加したルールを実行する npx textlint ファイル名 でtextlintを実行する 自動修正の機能に対応しているため、--fix オプションで自動修正できる npx textlint sample.txt # 実行結果 /Users/chick-p/Desktop/playground-textlint/sample.txt 1:27 ✓ error 【dict2】 "することができます"は冗長な表現です。"することが"を省き簡 解説: https://github.com/textlint-ja/textlint-rule-ja-no-redundant-expressio # 自動修正する npx textlint sample.txt --fix 29
30. 30 / 52 ルール選びは難しい 実際には、たくさんのルールの中からひとつずつ選択するのは大変 「スタイルガイドは準備中だよ」 「作る予定がない」 そんな人には、ルールプリセットがオススメ 30
31. 31 / 52 ルールプリセット ルールプリセットは、ルールの詰め合わせのこと ルールをひとつずつ選ぶ必要がない ルールプリセットを導入するだけでドキュメントの一貫性を担保できる 31
32. 32 / 52 ルールプリセットの例 日本翻訳連盟の日本語標準スタイルガイドを反映したルールプリセット - textlint-rule-preset-jtf-style 技術ドキュメント向けのルールプリセット - textlint-rule-preset-ja- technical-writing ルールプリセットを公開している企業もある ics.mediaさん - textlint-rule-preset-icmedia SmartHRさん - textlint-rule-preset-smarthr 弁護士ドットコムさん - textlint-rule-preset-bengo4 32
33. 33 / 52 ルールプリセットを使う ルールと同様に、インストールして、ルールの設定ファイルで有効にするだけ .textlintrc.json 運用に合わないルールがあれば、個別にルールをオフにできる（説明は割愛） # JTF日本語標準スタイルガイドのルールプリセット をインストール npm install textlint-rule-preset-ja-technical-writing { "plugins": {}, "filters": {}, "rules": { "preset-ja-technical-writing": true } } 33
34. 34 / 52 Step4: prhルールを活用する 34
35. 35 / 52 表記揺れをチェックする 表記揺れをチェックするにはtextlint-rule-prhというルールを使う prhルールを使う場合は、自社の表記ルールに合わせた辞書ファイルを準備する prhはproofreading helperの略で、校正（=proofread）を手伝ってくれる （=helper）という意味 35
36. 36 / 52 textlint-rule-prhをインストールする prhルールをインストールする # prhルールをインストール npm install textlint-rule-prh 36
37. 37 / 52 textlint-rule-prhルールを有効にする 設定ファイルで、ルールを有効にする .textlintrc.json 「prh.yml」は表記ルールを定義した辞書ファイル（これから作る） { "plugins": {}, "filters": {}, "rules": { "no-hankaku-kana": true, "prh": { "rulePaths": [ "./prh.yml" ] } } } 37
38. 38 / 52 辞書ファイル（prh.yml）を作る 1. テキストエディタで、次の内容を入力する version: 1 rules: - pattern: expected: 2. textlintをインストールしたディレクトリの下に、「prh.yml」というファイル 名で保存する YAMLというフォーマットはインデントが重要 行頭のスペースの数に注意
39. 39 / 52 例1：「二要素認証」をチェックする（1/2） 「二要素認証」をチェックし、「2要素認証」に修正する定義を追加する prh.yml プロパティの説明 pattern ：修正前の文字列 expected ：修正後の文字列 version: 1 rules: - pattern: 二要素認証 expected: 2要素認証 39
40. 40 / 52 例1：「二要素認証」をチェックする（2/2） npx textlint ファイル名 でtextlintを実行する 自動修正の機能に対応しているため、--fix オプションで自動修正できる npx textlint sample.txt # 実行結果 /Users/chick-p/Desktop/playground-textlint/sample.txt 1:16 ✓ error 二要素認証 => 2要素認証 prh ✖ 1 problem (1 error, 0 warnings) ✓ 1 fixable problem. Try to run: $ textlint --fix [file] # 自動修正する npx textlint sample.txt --fix 40
41. 41 / 52 例2：「ヘッダ」をチェックする（誤） expected に「ヘッダー」、pattern に「ヘッダ」と書く… prh.yml このままではダメ🙅 「ヘッダー」と書かれていたら、「ヘッダーー」になってしまう 単純に文字列を置換できない場合は、正規表現を使う version: 1 rules: - pattern: ヘッダ expected: ヘッダー 41
42. 42 / 52 正規表現 正規表現とは 正規表現は「いくつかの文字列を1つの形式で表現するための表現方法」のこと たとえば正規表現で、5桁の半角数字は[0-9]{5} という文字列で表現する prhルールで正規表現でチェックするとき pattern に、/正規表現/ を指定する prh.yml version: 1 rules: - pattern: /正規表現/ expected: 修正後の文字列 42
43. 43 / 52 例2：「ヘッダ」をチェックする（正） 「直後に長音がない」をチェックする場合は、否定先読み（?! ）を使う ?! は「"?! の直後に指定した表現"がないとき」を示す 「直後に長音がないとき」は、?!ー で表現する ヘッダ(?!ー) とすると、「"ヘッダー"ではない"ヘッダ"」を表現できる prh.yml version: 1 rules: - pattern: 二要素認証 expected: 2要素認証 - pattern: /ヘッダ(?!ー)/ expected: ヘッダー 43
44. 44 / 52 例3：「二要素認証」 「２段階認証」 「2段階認証」 をチェックする 「二要素認証」 「２段階認証」 「2段階認証」の表記揺れをチェックする 「AAまたはBBまたはCC」は、正規表現でAA|BB|CC と表す prh.yml チェック内容が重複するため、最初に書いた定義を削除している version: 1 rules: - pattern: /二要素認証|２要素認証|2段階認証/ expected: 2要素認証 - pattern: /ヘッダ(?!ー)/ expected: ヘッダー 44
45. 45 / 52 Step5：行単位でtextlintのルールを無効にする 45
46. 46 / 52 行単位でルールを無効にする ドキュメントの途中で、ルールを無効にしたいことがある 他社のUI文言を引用するとき 間違った例をあえて書きたいとき 特定の範囲だけルールを無効にしたいときは、textlint-filter-rule-commentsと いうフィルタールールを使う 46
47. 47 / 52 textlint-filter-rule-commentsをインストール する フィルタールールをインストールする # フィルタールールをインストール npm install textlint-filter-rule-comments 47
48. 48 / 52 textlint-filter-rule-commentsを有効にする 設定ファイルで、フィルタールールを有効にする 「.textrintrc.json」をテキストエディタで開いて、filter プロパティに追記す る .textlintrc.json { "plugins": {}, "filters": { "comments": true }, "rules": { // 省略 48
49. 49 / 52 ドキュメントで無効にする部分を明示する 無効にしたい部分を、<!-- textlint-disable ルール名 --> と<!-- textlint-enable ルール名 --> で囲む 例として、「textlint-rule-prh」を無効にする sample.txt npx textlint ファイル名 でtextlintを実行する <!-- textlint-disable prh --> 認証に使われる要素には、 「知識要素」 「所有要素」 「生体要素」の3つの要素があります。 2要素認証は、このうち2つの異なる要素を組み合わせて本人確認を行う方法です。 2段階認証は、2つの段階を経て本人確認を行う方法で、同じ要素を組み合わせることもあります。 <!-- textlint-enable prh --> 49
50. 50 / 52 まとめ
51. 51 / 52 まとめ textlintの導入方法や使い方について説明した textlintを使うと、スタイルガイドに沿っていない書きかたや表記揺れを、自動 的に検出し修正できる 51
52. 52 / 52 ご清聴ありがとうございました🐣