feat(i18n): Add Japanese (ja/) translation (#105)
- Translate all 101 markdown files: P1 core, all 10 modules, examples, auxiliary docs (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CLAUDE.md, etc.), peripheral docs (.github/, docs/, resources/, scripts/) - Translate comments and user-facing messages in 06-hooks/*.sh examples - Copy 05-mcp/*.json examples (standard JSON, no comments) - Update root README.md language switcher to include 日本語 - Add ja/TRANSLATION_NOTES.md (glossary + style guide) All translations pass pre-commit quality gates (markdown-lint, cross-references, mermaid-syntax, link-check, build-epub).
This commit is contained in:
JiangCheng
423
ja/TRANSLATION_NOTES.md
Normal file
423
ja/TRANSLATION_NOTES.md
Normal file
@@ -0,0 +1,423 @@
|
||||
# 翻訳用語集とスタイルガイド
|
||||
|
||||
# Translation Glossary & Style Guide
|
||||
|
||||
> **重要：** 本書は Claude Code ドキュメントを日本語へ翻訳する際のルールを定める。作業開始前に必ず読むこと。
|
||||
|
||||
## 基本方針
|
||||
|
||||
- **文体：** だ・である調（常体）
|
||||
- **用語方針：** カタカナ寄り（IT 業界で定着済みのカタカナ語を優先）
|
||||
- **コード保持：** 実行コードは 100% 維持。コメント・docstring のみ翻訳
|
||||
- **Mermaid 図：** ラベルテキストは英語のまま維持
|
||||
- **原典追従：** 各ファイル先頭に `i18n-source-sha` を埋め込み、再同期可能にする
|
||||
|
||||
---
|
||||
|
||||
## 技術用語集
|
||||
|
||||
全ファイルで統一するための対訳表：
|
||||
|
||||
| English | 日本語 | 備考 |
|
||||
|---------|--------|------|
|
||||
| slash command | スラッシュコマンド | Claude Code の機能名 |
|
||||
| hook | フック | IT 業界で定着 |
|
||||
| skill | スキル | Claude Code の機能名 |
|
||||
| subagent | サブエージェント | Claude Code の機能名 |
|
||||
| agent | エージェント | 一般的なカタカナ表記 |
|
||||
| memory | メモリ | Claude Code の機能名（記憶領域の意味） |
|
||||
| checkpoint | チェックポイント | セッションのスナップショット |
|
||||
| plugin | プラグイン | 一般用語 |
|
||||
| pull request / PR | プルリクエスト / PR | GitHub 用語 |
|
||||
| commit | コミット | Git 用語 |
|
||||
| branch | ブランチ | Git 用語 |
|
||||
| merge | マージ | Git 用語 |
|
||||
| MCP (Model Context Protocol) | MCP | プロトコル名はそのまま |
|
||||
| CLAUDE.md | CLAUDE.md | ファイル名はそのまま |
|
||||
| prompt | プロンプト | 定着したカタカナ |
|
||||
| workflow | ワークフロー | 定着したカタカナ |
|
||||
| repository | リポジトリ | Git 用語 |
|
||||
| issue | Issue | GitHub 用語、原文表記 |
|
||||
| release | リリース | 定着したカタカナ |
|
||||
| API | API | そのまま |
|
||||
| CLI | CLI | Command-Line Interface、そのまま |
|
||||
| CI/CD | CI/CD | そのまま |
|
||||
| pre-commit hook | pre-commit フック | ツール名は維持 |
|
||||
| environment variable | 環境変数 | 訳語が定着 |
|
||||
| dependencies | 依存関係 | 訳語が定着 |
|
||||
| template | テンプレート | カタカナ |
|
||||
| worktree | ワークツリー | Git 用語、カタカナ化 |
|
||||
| frontmatter | フロントマター | YAML 先頭ブロック |
|
||||
| token | トークン | カタカナ |
|
||||
| context window | コンテキストウィンドウ | カタカナ |
|
||||
| fork | フォーク | Git 用語 |
|
||||
| clone | クローン（する） | Git 用語 |
|
||||
| sandbox | サンドボックス | カタカナ |
|
||||
| boilerplate | ボイラープレート | カタカナ |
|
||||
| debugging | デバッグ | カタカナ |
|
||||
| linting | リンティング | カタカナ |
|
||||
| refactoring | リファクタリング | カタカナ |
|
||||
| build | ビルド | カタカナ |
|
||||
| deploy | デプロイ | カタカナ |
|
||||
| feature | 機能 | 文脈に応じて「フィーチャー」も可 |
|
||||
| user | ユーザー | カタカナ |
|
||||
| developer | 開発者 | 訳語が定着 |
|
||||
| documentation | ドキュメント / ドキュメンテーション | 短縮形「ドキュメント」を優先 |
|
||||
| roadmap | ロードマップ | カタカナ |
|
||||
| ecosystem | エコシステム | カタカナ |
|
||||
| orchestration | オーケストレーション | カタカナ |
|
||||
| permission | 権限 / パーミッション | 文脈に応じて |
|
||||
| settings | 設定 | 訳語が定着 |
|
||||
| configuration | 設定 / コンフィグ | 短縮形「設定」を優先 |
|
||||
| trigger | トリガー | カタカナ |
|
||||
| event | イベント | カタカナ |
|
||||
| script | スクリプト | カタカナ |
|
||||
| handler | ハンドラ | カタカナ |
|
||||
| wrapper | ラッパー | カタカナ |
|
||||
| middleware | ミドルウェア | カタカナ |
|
||||
| pipeline | パイプライン | カタカナ |
|
||||
| best practice | ベストプラクティス | カタカナ |
|
||||
| use case | ユースケース | カタカナ |
|
||||
| trade-off | トレードオフ | カタカナ |
|
||||
|
||||
---
|
||||
|
||||
## Claude Code 固有名詞（絶対変更不可）
|
||||
|
||||
以下は Claude Code の **製品名・機能名** であり、**訳さず英語表記のまま** 維持する：
|
||||
|
||||
| 表記 | 種別 | 補足 |
|
||||
|------|------|------|
|
||||
| Claude | 製品名 | カタカナ「クロード」にしない |
|
||||
| Claude Code | 製品名 | そのまま |
|
||||
| Anthropic | 会社名 | そのまま |
|
||||
| CLAUDE.md | ファイル名 | 大文字維持 |
|
||||
| SKILL.md | ファイル名 | 大文字維持 |
|
||||
| MCP / Model Context Protocol | プロトコル名 | 略語使用、初出は併記 |
|
||||
| `.claude/` | ディレクトリ名 | そのまま |
|
||||
| `~/.claude/` | パス | そのまま |
|
||||
| `claude.ai` / `claude.com` / `code.claude.com` | URL | そのまま |
|
||||
| Sonnet / Opus / Haiku | モデル名 | カタカナにしない |
|
||||
|
||||
ただし、**機能カテゴリ** は日本語化する（カタカナ寄り）：
|
||||
|
||||
| English | 日本語 | 備考 |
|
||||
|---------|--------|------|
|
||||
| Slash Commands（機能名） | スラッシュコマンド | 見出しでも翻訳する |
|
||||
| Memory（機能名） | メモリ | 「記憶」とは訳さない |
|
||||
| Skills（機能名） | スキル | そのまま |
|
||||
| Subagents（機能名） | サブエージェント | 「副エージェント」NG |
|
||||
| Hooks（機能名） | フック | そのまま |
|
||||
| Plugins（機能名） | プラグイン | そのまま |
|
||||
| Checkpoints（機能名） | チェックポイント | そのまま |
|
||||
| Advanced Features（カテゴリ） | 高度な機能 | 訳す |
|
||||
| CLI Reference（カテゴリ） | CLI リファレンス | 訳す |
|
||||
|
||||
---
|
||||
|
||||
## モジュール名の取り扱い
|
||||
|
||||
各モジュールの見出し・URL での扱い：
|
||||
|
||||
| 原典の見出し | 日本語訳 | URL（変更しない） |
|
||||
|-----------|--------|--------------|
|
||||
| 01 Slash Commands | スラッシュコマンド | `01-slash-commands/` |
|
||||
| 02 Memory | メモリ | `02-memory/` |
|
||||
| 03 Skills | スキル | `03-skills/` |
|
||||
| 04 Subagents | サブエージェント | `04-subagents/` |
|
||||
| 05 MCP | MCP | `05-mcp/` |
|
||||
| 06 Hooks | フック | `06-hooks/` |
|
||||
| 07 Plugins | プラグイン | `07-plugins/` |
|
||||
| 08 Checkpoints | チェックポイント | `08-checkpoints/` |
|
||||
| 09 Advanced Features | 高度な機能 | `09-advanced-features/` |
|
||||
| 10 CLI | CLI | `10-cli/` |
|
||||
|
||||
**重要：** ディレクトリ名・ファイルパスは絶対に変更しない。日本語化するのは見出し・本文中の言及のみ。
|
||||
|
||||
---
|
||||
|
||||
## 翻訳ルール
|
||||
|
||||
### 1. コードとコマンド
|
||||
|
||||
**黄金ルール：** 実行可能コードは 100% 保持する。翻訳するのはコメントと説明文のみ。
|
||||
|
||||
**正しい例（✅）：**
|
||||
|
||||
````markdown
|
||||
このコマンドを実行するには：
|
||||
|
||||
```bash
|
||||
/optimize
|
||||
```
|
||||
|
||||
このコマンドはコードを解析する。
|
||||
````
|
||||
|
||||
**誤った例（❌）：**
|
||||
|
||||
````markdown
|
||||
このコマンドを実行するには：
|
||||
|
||||
```bash
|
||||
/最適化 # コマンド名は絶対に翻訳しない
|
||||
```
|
||||
````
|
||||
|
||||
### 2. コード内コメント
|
||||
|
||||
コメントは日本語に翻訳する：
|
||||
|
||||
```python
|
||||
# ✅ 正しい — コメントを翻訳
|
||||
# このスラッシュコマンドはコードを最適化する
|
||||
def optimize_code():
|
||||
pass
|
||||
|
||||
# ❌ 誤り — 関数名は翻訳しない
|
||||
def 最適化_コード(): # 関数名は変更しない
|
||||
pass
|
||||
```
|
||||
|
||||
### 3. 関数名・変数名・クラス名
|
||||
|
||||
英語のまま維持する：
|
||||
|
||||
```python
|
||||
# ✅ 正しい
|
||||
def create_subagent(name: str, system_prompt: str):
|
||||
pass
|
||||
|
||||
# ❌ 誤り
|
||||
def サブエージェント作成(名前: str, システムプロンプト: str):
|
||||
pass
|
||||
```
|
||||
|
||||
### 4. Mermaid 図
|
||||
|
||||
**100% そのまま維持する。** mermaid ブロック内のテキストは一切翻訳しない。
|
||||
|
||||
````markdown
|
||||
<!-- ❌ 誤り -->
|
||||
```mermaid
|
||||
graph TD
|
||||
A[ユーザー] --> B[エージェント]
|
||||
```
|
||||
|
||||
<!-- ✅ 正しい -->
|
||||
```mermaid
|
||||
graph TD
|
||||
A[User] --> B[Agent]
|
||||
```
|
||||
````
|
||||
|
||||
**重要：** Mermaid のコメントは `%%` を使う。`#` はパーサエラーになる。
|
||||
|
||||
````markdown
|
||||
<!-- ✅ 正しい -->
|
||||
```mermaid
|
||||
graph TD
|
||||
%% これは Mermaid のコメント
|
||||
A[User] --> B[Agent]
|
||||
```
|
||||
|
||||
<!-- ❌ 誤り -->
|
||||
```text
|
||||
graph TD
|
||||
# これはパーサを壊す！
|
||||
A[User] --> B[Agent]
|
||||
```
|
||||
````
|
||||
|
||||
### 5. ファイルパスと URL
|
||||
|
||||
そのまま維持する：
|
||||
|
||||
```markdown
|
||||
<!-- ✅ 正しい -->
|
||||
設定については `.claude/settings.json` を参照。
|
||||
|
||||
<!-- ❌ 誤り -->
|
||||
設定については `.claude/設定.json` を参照。
|
||||
```
|
||||
|
||||
### 6. テーブル
|
||||
|
||||
構造（列・行数）はそのまま維持する。テキスト内容は翻訳し、技術的な値はそのままにする：
|
||||
|
||||
```markdown
|
||||
| コマンド | 説明 | 例 |
|
||||
|---------|------|-----|
|
||||
| `/help` | ヘルプを表示 | `/help memory` |
|
||||
| `/clear` | セッションをクリア | `/clear` |
|
||||
```
|
||||
|
||||
### 7. ファイル間リンク
|
||||
|
||||
`ja/` 内では相対パスを使う：
|
||||
|
||||
```markdown
|
||||
<!-- モジュール間 -->
|
||||
[メモリ](../02-memory/)
|
||||
|
||||
<!-- 英語の原典へ -->
|
||||
[English version](../../README.md)
|
||||
|
||||
<!-- コードファイル — 原典を参照する。コピーしない -->
|
||||
[`format-code.sh`](../../06-hooks/format-code.sh)
|
||||
```
|
||||
|
||||
### 8. バージョントラッキング用フロントマター
|
||||
|
||||
各翻訳ファイルの先頭に、原典のバージョン追跡用 HTML コメントを付ける：
|
||||
|
||||
```markdown
|
||||
<!-- 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：説明文を翻訳する
|
||||
|
||||
```markdown
|
||||
スラッシュコマンドは、Claude の対話セッション中の動作を制御するショートカットである。
|
||||
```
|
||||
|
||||
### ✅ DO：コード内のコメントを翻訳する
|
||||
|
||||
```python
|
||||
# ✅ 正しい
|
||||
# この関数は新しいサブエージェントを作成する
|
||||
def create_subagent():
|
||||
pass
|
||||
```
|
||||
|
||||
### ❌ DON'T：関数名を翻訳しない
|
||||
|
||||
```python
|
||||
# ❌ 誤り
|
||||
def サブエージェント作成():
|
||||
pass
|
||||
|
||||
# ✅ 正しい
|
||||
def create_subagent():
|
||||
pass
|
||||
```
|
||||
|
||||
### ❌ DON'T：Mermaid 図を翻訳しない
|
||||
|
||||
````markdown
|
||||
<!-- ❌ 誤り -->
|
||||
```mermaid
|
||||
graph TD
|
||||
A[ユーザー] --> B[エージェント]
|
||||
```
|
||||
|
||||
<!-- ✅ 正しい -->
|
||||
```mermaid
|
||||
graph TD
|
||||
A[User] --> B[Agent]
|
||||
```
|
||||
````
|
||||
|
||||
### ❌ DON'T：機械翻訳を無検証で使わない
|
||||
|
||||
機械翻訳（Google 翻訳、DeepL など）は以下の問題を起こしやすい：
|
||||
|
||||
- 技術用語の誤訳
|
||||
- コードの文脈を理解しない
|
||||
- コマンドの意味を歪める
|
||||
- Markdown 書式を壊す
|
||||
|
||||
**機械翻訳の後は必ず人手でチェック・編集すること。**
|
||||
|
||||
### ❌ DON'T：コミットメッセージ例を翻訳しない
|
||||
|
||||
Conventional Commits 形式は規約のため、英語のまま維持する：
|
||||
|
||||
```markdown
|
||||
<!-- ✅ 正しい -->
|
||||
- `feat(slash-commands): Add API documentation generator`
|
||||
|
||||
<!-- ❌ 誤り -->
|
||||
- `機能追加(slash-commands): API ドキュメント生成機能を追加`
|
||||
```
|
||||
|
||||
### ❌ DON'T：CLI 出力例を翻訳しない
|
||||
|
||||
実際のコマンド出力を示している例は、英語のまま維持する（再現性のため）：
|
||||
|
||||
```text
|
||||
✅ 正しい：
|
||||
$ 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）
|
||||
Reference in New Issue
Block a user