全ファイル日本語化: ポリシーと非翻訳ルールを確定する #3
Description
親 Issue: #2
目的
全ファイル日本語化を進める前に、どこまでを翻訳対象にし、何を英語のまま残すかを明文化する。
ステータス
- この Issue を日本語化ポリシーの source of truth とする
- 全ファイル日本語化: ルート docs / config を日本語化する #4 から 全ファイル日本語化: テスト・fixture・eval baseline を更新する #10 の着手判断はこの Issue の内容に従う
合意済みポリシー
翻訳しないもの
- CLI コマンド名
- slash command 名
- JSON key
- package metadata
- ブランド名・固有名詞
- 例:
gstack,Claude Code,Playwright
- 例:
LICENSE の扱い
- 英語原文の
LICENSEは維持する - 日本語参考訳は別ファイルで持つ
- 日本語版は参考訳であり、法的な正本は英語原文であることを明記する
- 参考訳ファイルはルート docs 変更の一部として追加する
提案ポリシー
優先順位
- user-facing 文言を最優先で日本語化する
- README / docs / skill templates / generated docs
- CLI の help / error / log / 実行時メッセージ
- UI テキスト
- テンプレート文面
- user-facing 文言に追随するテスト fixture / ground truth / assertion を日本語化する
- 内部コメントは repo 全体の必須対象にはしない
- ただし、対象ファイルを編集する際に、そのコメントが user-facing 文言の理解や保守に直結するなら翻訳してよい
- 完了条件は「内部コメントの全翻訳」ではなく「user-facing 文言の一貫した日本語化」を優先する
fixture / eval ground truth の扱い
- 画面表示文言、説明文、期待される自然言語出力は日本語化する
- 機械可読な契約は維持する
- 例: JSON key、schema、selector、id、class、data attribute、コマンド名、ファイルパス、環境変数名
- 既存テストが英語文言を前提にしている場合は、日本語化後の期待値へ更新する
- ただし、fixture が「英語 UI の再現」や「外部サービスの原文」を意図している場合は英語維持を許可し、理由を残す
docs / コード例 / テンプレートの扱い
- 説明文、見出し、注記、自然言語のサンプルは日本語化する
- コードブロック内の識別子・コマンド・API 名・env var・JSON key は原則維持する
- コードコメントは必須翻訳対象ではないが、対象ファイルを触る中で説明の主文が英語のままだと読者理解を阻害する場合は翻訳してよい
用語運用
- 製品名、OSS 名、サービス名、ライブラリ名は原語維持
- slash command や CLI 使用例は、呼び出し文字列そのものを維持したうえで周辺説明を日本語化する
- 不自然な直訳は避け、開発者向けドキュメントとして自然な日本語を優先する
後続 Issue への適用ルール
- 全ファイル日本語化: ルート docs / config を日本語化する #4: ルート docs / config
package.jsonの機械可読 metadata は維持し、説明文レベルのみ必要に応じて扱うLICENSE本体は変更せず、日本語参考訳ファイルを別ファイルで追加する
- 全ファイル日本語化: skill テンプレートを日本語化する #5: skill templates
.tmplを source of truth とし、識別子・placeholder・コマンド名は維持する
- 全ファイル日本語化: browse の実行時文言と UI テキストを日本語化する #6: browse 実行時文言 / UI
COMMAND_DESCRIPTIONSの説明文や usage の自然言語部分は日本語化する- コマンド literal は維持する
- 全ファイル日本語化: review / qa 補助ドキュメントを日本語化する #7: review / qa 補助 docs
- ガイド本文とテンプレート文面を日本語化し、フォーマット上の識別子は維持する
- 全ファイル日本語化: scripts / bin / setup のメッセージを日本語化する #8: scripts / bin / setup
- 人が読むログ・説明・エラーは日本語化する
- 機械処理前提の出力形式は壊さない
- 全ファイル日本語化: generated SKILL.md を再生成して整合性を取る #9: generated
SKILL.md - 全ファイル日本語化: テスト・fixture・eval baseline を更新する #10: tests / fixtures / eval baseline
- 日本語化によって壊れた assertion / expected output / fixture を更新する
非翻訳扱いの一覧
LICENSE英語原文- CLI コマンド名
- slash command 名
- JSON key
- package metadata
- ブランド名・固有名詞
- コード識別子、API 名、env var、selector、id、class、data attribute、ファイルパス
成果物
- 日本語化ポリシーの文書化
- 非翻訳扱いにするファイル/識別子の一覧
- 後続 Issue が迷わず着手できる判断基準
完了条件
- 少なくとも 全ファイル日本語化: ルート docs / config を日本語化する #4 全ファイル日本語化: skill テンプレートを日本語化する #5 全ファイル日本語化: browse の実行時文言と UI テキストを日本語化する #6 全ファイル日本語化: review / qa 補助ドキュメントを日本語化する #7 全ファイル日本語化: scripts / bin / setup のメッセージを日本語化する #8 全ファイル日本語化: generated SKILL.md を再生成して整合性を取る #9 全ファイル日本語化: テスト・fixture・eval baseline を更新する #10 が参照できる形でルールがまとまっている
- 翻訳対象と非翻訳対象の境界が明文化されている
LICENSEの扱いが明記されている