Documentation

documentation

公開ツールやエージェント向けの READMEs / docs を、英語を既定・日本語をミラー として 2 言語で整備するための共通方針。

命名規約

• 英語版: 拡張子なし — README.md / docs/path.md / docs/content.md
• 日本語版: .ja.md 接尾辞 — README.ja.md / docs/path.ja.md / docs/content.ja.md
• 同一トピックの 2 言語版は 兄弟ファイル として並べる（docs/en/ のようなサブディレクトリで分けない）

言語セレクタヘッダー

各ファイルの H1 直下に、現在言語を太字・他言語をリンクで表すセレクタを置く。

英語版:

# <Title>

> [日本語](./<basename>.ja.md) | **English**

日本語版:

# <タイトル>

> **日本語** | [English](./<basename>.md)

トップレベル README.md / README.ja.md も同形式。

内部リンク

兄弟参照は 同言語の対応版 を指す。

• 英語版 (docs/foo.md) の [bar](bar.md) → 英語版 bar.md
• 日本語版 (docs/foo.ja.md) の [bar](bar.ja.md) → 日本語版 bar.ja.md

トップレベル README からの参照も同じ規則:

• README.md → docs/foo.md
• README.ja.md → docs/foo.ja.md

同期ルール

ドキュメントを編集するときは 両言語を同じ PR で更新 する。

• 新規追加: foo.md と foo.ja.md を同時に作成
• 内容変更: 片方だけの編集は許容しない（部分翻訳の取り残し原因）
• リネーム: 両言語版を同時にリネーム
• 削除: 両言語版を同時に削除

英語が源泉とは限らない。実装者が日本語で書いた内容を後から英訳しても、最終 PR では両方そろえる。

翻訳の取り扱い

• コードブロック・YAML・CLI 出力例・ファイルパス・パッケージ名は 逐語維持
• 表のセル内テキストは翻訳、表構造は維持
• ツール固有名詞（Claude Code / Cursor / GitHub Actions / npm 等）は原語のまま
• 出力例の中の人間向けメッセージはその言語に合わせて訳す
• ソース整合性マーカー（プロジェクトが採用していれば）の行は逐語維持。ハッシュ・パスは言語ごとに変えない

新規ドキュメント追加時の手順

1. 英語版 docs/<name>.md を H1 + 言語セレクタヘッダー付きで作成
2. 日本語版 docs/<name>.ja.md を作成（同じ構造、翻訳した本文）
3. ソース整合性マーカーが必要なセクションは両言語版に同一で配置
4. docs/README.md と docs/README.ja.md の索引に追加
5. ルートの README.md / README.ja.md でも紹介すべきトピックなら追記
6. プロジェクトの doc lint がある場合はローカルで実行して検証
7. PR では両言語版を 1 コミットにまとめる

他スキルとの関係

• implementation — ドキュメント変更を含む実装でステップ 5 で命名・同期ルールを併用
• improvement — スキル紹介を更新する際の参照元
• direction — エージェント可読性（legibility）の観点で構造判断を伴うときに併用

アンチパターン

• 片言語のみ更新して他方を放置 → 部分翻訳の取り残し原因
• 言語別にディレクトリを分ける（docs/en/ / docs/ja/ 等）→ 兄弟ファイル方式の方が検索性とリンク管理が単純
• セレクタヘッダーを省略 → 利用者が代替言語版に到達できない
• ソース整合性マーカーのハッシュを言語版ごとに変える → ソース 1 個に対し複数ハッシュは意味矛盾
• 翻訳ミラーを巨大 PR 検出（diff size 等）にカウントする → 構造的に大きくなる翻訳 PR で警告が誤発動する

Source: Mulyu/okite — distributed by TomeVault.