[miyako]

なぜ

i18n/ja の日本語ドキュメントでは、同じテクニカル用語が ユーザ / ユーザー、インタフェース / インターフェイス / インターフェース のように複数の表記で混在していました。レビューのたびに人手で指摘するのは現実的ではないため、用語集にもとづいて機械的に検査・修正できる仕組みを用意します。

アプローチ

用語集 (TSV) を唯一の正とし、追加の npm パッケージなしで動作する変換エンジンを tools/ja-normalize に追加しました。ルールを足したい場合はスクリプトではなく TSV を編集します。

• glossary.tsv — 変換前 / 変換後 / 備考 のタブ区切り。記述順は不問 (常に長い表記が優先)
• exceptions.tsv — keep (メモリ、ライブラリ、クエリ等、長音を付けない語のガード)、literal、regex、path
• normalize.js / index.js / test.js — 変換エンジン、CLI、16 件のテスト
• npm run ja:check / ja:fix / ja:test

あわせて、用語集で正規化した結果を既存ドキュメント全体に一括適用しています (2264 ファイル / 8782 箇所)。

安全策

Markdown の構造や実行可能なコード例を壊さないよう、以下は変換対象から除外しています。

• コードフェンスとインラインコード、HTML タグ/属性/コメント、URL、リンク先のパス部分
• front matter のキー名と、title / description / sidebar_label / keywords 以外の値
• 翻訳 JSON (code.json 等) では "message" の値以外すべて

変換の性質として以下を保証し、テストで固定しています。

• 冪等性: 変換後 = 変換前 + ー のルールは (?!ー) で保護され、長音が二重に付きません
• 最長一致: ストアード → ストアド が プロシージャ → プロシージャー より先に適用されます
• 収束性: 多段変換 (ストアードプロシージャ → ストアドプロシージャー) が 1 回の実行で収束します
• リンク維持: 見出しと同一ページ内アンカー (#見出し) を同時に変換するため、リンク切れが発生しません
• 用語集に矛盾した定義や循環定義があると、実行時にエラーで停止します

自動実行

• .github/workflows/ja-normalize.yml — i18n/ja/** を含む PR / push で検査し、表記ゆれがあれば失敗します。workflow_dispatch で mode: fix を選ぶと一括修正の PR を自動作成します
• .githooks/pre-commit — 任意で有効化できるコミット前チェック (git config core.hooksPath .githooks)

レビューで注目してほしい点

• 用語集の内容そのもの — 変換ロジックよりも glossary.tsv の妥当性が重要です。ユーザインタフェース は汎用ルール インタフェース → インターフェース と ユーザ → ユーザー の組み合わせで ユーザーインターフェース になります
• 一括適用のコミット — 差分は大きいですが、docs(ja): normalize technical terminology の 1 コミットに分離してあり、すべて機械的な置換です
• Crowdin との関係 — i18n/ja は Crowdin から取り込まれるため、このリポジトリだけを直しても次回のダウンロードで戻る可能性があります。運用として crowdin-download 直後に npm run ja:fix を流し、同じ用語集を Crowdin の用語集 / QA にも登録することを README に記載しています

ドキュメント

• tools/ja-normalize/README.md — 仕様とルールの書き方
• tools/ja-normalize/HOWTO.md — GitHub Actions に不慣れな編集者向けに、ブラウザーだけで手動実行・例外追加をおこなう手順書

確認したこと

• npm run ja:test — 16 件すべて成功
• npm run ja:check — 8762 ファイルで残 0 件 (一括適用後)
• 適用後の翻訳 JSON 10 件がすべて JSON として妥当であること
• 再実行しても差分が発生しないこと (冪等性)