Translation Glossary & Style Guide

重要： 本書は Claude Code ドキュメントを日本語へ翻訳する際のルールを定める。作業開始前に必ず読むこと。

基本方針

• 文体： だ・である調（常体）
• 用語方針： カタカナ寄り（IT 業界で定着済みのカタカナ語を優先）
• コード保持： 実行コードは 100% 維持。コメント・docstring のみ翻訳
• Mermaid 図： ラベルテキストは英語のまま維持
• 原典追従： 各ファイル先頭に i18n-source-sha を埋め込み、再同期可能にする

技術用語集

全ファイルで統一するための対訳表：

Claude Code 固有名詞（絶対変更不可）

以下は Claude Code の 製品名・機能名 であり、訳さず英語表記のまま 維持する：

ただし、機能カテゴリ は日本語化する（カタカナ寄り）：

モジュール名の取り扱い

各モジュールの見出し・URL での扱い：

重要： ディレクトリ名・ファイルパスは絶対に変更しない。日本語化するのは見出し・本文中の言及のみ。

翻訳ルール

1. コードとコマンド

黄金ルール： 実行可能コードは 100% 保持する。翻訳するのはコメントと説明文のみ。

正しい例（✅）：

このコマンドを実行するには：

```bash
/optimize
```

このコマンドはコードを解析する。

誤った例（❌）：

このコマンドを実行するには：

```bash
/最適化  # コマンド名は絶対に翻訳しない
```

2. コード内コメント

コメントは日本語に翻訳する：

# ✅ 正しい — コメントを翻訳
# このスラッシュコマンドはコードを最適化する
def optimize_code():
    pass

# ❌ 誤り — 関数名は翻訳しない
def 最適化_コード():  # 関数名は変更しない
    pass

3. 関数名・変数名・クラス名

英語のまま維持する：

# ✅ 正しい
def create_subagent(name: str, system_prompt: str):
    pass

# ❌ 誤り
def サブエージェント作成(名前: str, システムプロンプト: str):
    pass

4. Mermaid 図

100% そのまま維持する。 mermaid ブロック内のテキストは一切翻訳しない。

<!-- ❌ 誤り -->
```mermaid
graph TD
    A[ユーザー] --> B[エージェント]
```

<!-- ✅ 正しい -->
```mermaid
graph TD
    A[User] --> B[Agent]
```

重要： Mermaid のコメントは %% を使う。# はパーサエラーになる。

<!-- ✅ 正しい -->
```mermaid
graph TD
    %% これは Mermaid のコメント
    A[User] --> B[Agent]
```

<!-- ❌ 誤り -->
```text
graph TD
    # これはパーサを壊す！
    A[User] --> B[Agent]
```

5. ファイルパスと URL

そのまま維持する：

<!-- ✅ 正しい -->
設定については `.claude/settings.json` を参照。

<!-- ❌ 誤り -->
設定については `.claude/設定.json` を参照。

6. テーブル

構造（列・行数）はそのまま維持する。テキスト内容は翻訳し、技術的な値はそのままにする：

| コマンド | 説明 | 例 |
|---------|------|-----|
| `/help` | ヘルプを表示 | `/help memory` |
| `/clear` | セッションをクリア | `/clear` |

7. ファイル間リンク

ja/ 内では相対パスを使う：

<!-- モジュール間 -->
[メモリ](../02-memory/)

<!-- 英語の原典へ -->
[English version](../../README.md)

<!-- コードファイル — 原典を参照する。コピーしない -->
[`format-code.sh`](../../06-hooks/format-code.sh)

8. バージョントラッキング用フロントマター

各翻訳ファイルの先頭に、原典のバージョン追跡用 HTML コメントを付ける：

<!-- i18n-source: 01-slash-commands/README.md -->
<!-- i18n-source-sha: a1b2c3d4 -->
<!-- i18n-date: 2026-04-27 -->

# 翻訳されたファイルの見出し

SHA は元になった英語ファイルの短縮コミットハッシュ。取得方法：git log --oneline -1 -- <英語ファイルへのパス>。

9. 文体ルール

• 基本文体： だ・である調（常体）。例：「〜である」「〜する」「〜だ」
• 読者への呼びかけ： 「あなた」は使わず、命令形か「〜できる」「〜してほしい」を使う
• 見出し・箇条書き： 体言止め可（「インストール」「設定方法」など）
• 本文： 常体で統一
• 冗長表現を避ける： 「実行する」 > 「実行を行う」
• 技術略語： 初出時は「正式名称（略語）」、以降は略語のみ
• 数字： 半角数字を使用（10 個、3 ステップなど）
• 句読点： 「、」と「。」を使用（「，」「．」は使わない）
• 括弧： 全角（）を使うが、コード内は半角 ()

10. 「ですます」と「である」の境界

• 本文・説明： である調
  • 「この機能は CLAUDE.md ファイルから設定を読み込む」
• 箇条書きの末尾： 体言止めまたは常体
  • 「インストール手順」「メモリの管理方法」
• コードのコメント内： である調 or 簡潔な体言止め
  • # このフックはコミット前に実行される
• 見出し： 体言止めまたは疑問形
  • 「## はじめに」「## なぜ必要か」

DO / DON'T

✅ DO：説明文を翻訳する

スラッシュコマンドは、Claude の対話セッション中の動作を制御するショートカットである。

✅ DO：コード内のコメントを翻訳する

# ✅ 正しい
# この関数は新しいサブエージェントを作成する
def create_subagent():
    pass

❌ DON'T：関数名を翻訳しない

# ❌ 誤り
def サブエージェント作成():
    pass

# ✅ 正しい
def create_subagent():
    pass

❌ DON'T：Mermaid 図を翻訳しない

<!-- ❌ 誤り -->
```mermaid
graph TD
    A[ユーザー] --> B[エージェント]
```

<!-- ✅ 正しい -->
```mermaid
graph TD
    A[User] --> B[Agent]
```

❌ DON'T：機械翻訳を無検証で使わない

機械翻訳（Google 翻訳、DeepL など）は以下の問題を起こしやすい：

• 技術用語の誤訳
• コードの文脈を理解しない
• コマンドの意味を歪める
• Markdown 書式を壊す

機械翻訳の後は必ず人手でチェック・編集すること。

❌ DON'T：コミットメッセージ例を翻訳しない

Conventional Commits 形式は規約のため、英語のまま維持する：

<!-- ✅ 正しい -->
- `feat(slash-commands): Add API documentation generator`

<!-- ❌ 誤り -->
- `機能追加(slash-commands): API ドキュメント生成機能を追加`

❌ DON'T：CLI 出力例を翻訳しない

実際のコマンド出力を示している例は、英語のまま維持する（再現性のため）：

✅ 正しい：
$ claude --version
2.1.119

❌ 誤り：
$ claude --version
バージョン 2.1.119

コミット前チェックリスト

• 技術的正確性が保たれている
• 日本語として自然に読める
• 用語が glossary と一致している
• コードは 100% そのまま（変更なし）
• Mermaid 図は変更されていない
• 内部リンクが機能する
• 外部リンクが保持されている
• Markdown 書式が正しい
• コード内コメントが翻訳されている
• 関数名・変数名・クラス名は英語のまま
• ファイルパスと URL は変更なし
• フロントマター i18n-source-sha を追加済み
• pre-commit チェックがすべて通る

困ったとき

翻訳中に疑問が生じたら：

1. 本書の glossary を確認
2. 他モジュールの類似ファイルがどう訳されているか確認
3. uk/、vi/、zh/ の対応ファイルを参照
4. 必要なら GitHub Issue を立てて議論

最終更新： 2026-04-27 言語： 日本語（ja-JP）