translate-reading

name	translate-reading
description	원본 reading을 한국어로 번역하여 마크다운 파일로 저장합니다. 다단계 에이전트 파이프라인(용어검색→번역→정제→검증→QA→요약)으로 고품질 번역 생성. YouTube 콘텐츠의 경우 챕터별 요약도 자동 생성. 사용: /translate-reading week1/slug 또는 /translate-reading week1/parent/child
arguments	[{"name":"path","description":"week/slug 또는 week/parent/child 형식의 문서 경로\n- 단일 페이지: week1/how-openai-uses-codex\n- 자식 페이지: week1/prompt-engineering-guide/zeroshot\n","required":true},{"name":"refine-only","description":"기존 번역본의 품질만 개선 (translator 단계 스킵)","required":false},{"name":"skip-qa","description":"QA 단계를 스킵 (빠른 번역용)","required":false},{"name":"skip-summary","description":"요약 단계를 스킵 (YouTube 콘텐츠에서도 요약 생략)","required":false},{"name":"all-chapters","description":"YouTube 디렉토리의 모든 챕터를 순차적으로 번역\n--all-chapters 옵션으로 사용\n디렉토리 내 모든 .md 파일(인덱스 제외)을 번역\n","required":false}]

translate-reading Skill

원본 reading을 한국어로 번역하여 마크다운 파일로 저장합니다.

사용법

# 단일 페이지
/translate-reading <week/slug>
/translate-reading <week/slug> --refine-only
/translate-reading <week/slug> --skip-qa
/translate-reading <week/slug> --skip-summary

# 계층적 구조 (자식 페이지 / YouTube 챕터)
/translate-reading <week/parent/child>
/translate-reading <week/parent/child> --skip-qa

# YouTube 전체 챕터 일괄 번역
/translate-reading <week/slug> --all-chapters

예시

단일 페이지

/translate-reading week1/how-openai-uses-codex
/translate-reading week2/mcp-introduction

YouTube 챕터별 번역

# 개별 챕터 번역
/translate-reading week1/deep-dive-llms/introduction
/translate-reading week1/deep-dive-llms/tokenization
/translate-reading week1/deep-dive-llms/neural-network-io --skip-qa

# 전체 챕터 일괄 번역 (순차 실행)
/translate-reading week1/deep-dive-llms --all-chapters
/translate-reading week1/deep-dive-llms --all-chapters --skip-qa

계층적 구조 (수동 설정된 자식 페이지)

/translate-reading week1/prompt-engineering-guide/zeroshot
/translate-reading week1/prompt-engineering-guide/fewshot
/translate-reading week1/prompt-engineering-guide/cot --skip-qa

입출력

단일 페이지

• 입력: docs/week{N}/{slug}/eng/index.md (영문 원문)
• 출력: docs/week{N}/{slug}/kr/index.md (한국어 번역본)

YouTube 챕터 (자동 분리된 경우)

• 입력: docs/week{N}/{slug}/eng/{childSlug}.md (영문 원문)
• 출력: docs/week{N}/{slug}/kr/{childSlug}.md (한국어 번역본)

--all-chapters 모드

• 입력: docs/week{N}/{slug}/eng/ 디렉토리의 모든 .md 파일
• 출력: docs/week{N}/{slug}/kr/ 디렉토리에 번역본 생성
• 제외: _index.md (별도 처리 필요)

계층적 구조 (수동 설정)

• 입력: docs/week{N}/{parent-slug}/eng/{child-slug}.md (영문 원문)
• 출력: docs/week{N}/{parent-slug}/kr/{child-slug}.md (한국어 번역본)

경로 예시

# 단일 페이지
week1/how-openai-uses-codex
→ 입력: docs/week1/how-openai-uses-codex/eng/index.md
→ 출력: docs/week1/how-openai-uses-codex/kr/index.md

# YouTube 챕터 (개별)
week1/deep-dive-llms/tokenization
→ 입력: docs/week1/deep-dive-llms/eng/tokenization.md
→ 출력: docs/week1/deep-dive-llms/kr/tokenization.md

# YouTube 챕터 (전체)
week1/deep-dive-llms --all-chapters
→ 입력: docs/week1/deep-dive-llms/eng/*.md
→ 출력: docs/week1/deep-dive-llms/kr/*.md (24개 파일)

# 수동 계층 구조
week1/prompt-engineering-guide/zeroshot
→ 입력: docs/week1/prompt-engineering-guide/eng/zeroshot.md
→ 출력: docs/week1/prompt-engineering-guide/kr/zeroshot.md

• 참조: docs/glossary.md (용어집)

Note: readings.ts 업데이트는 별도 스킬(/upload-reading)이 담당합니다.

워크플로우

이 스킬은 Task tool을 사용하여 각 에이전트를 순차적으로 실행합니다.

/translate-reading week1/deep-dive-llms
           │
           ▼
┌──────────────────────────────────────┐
│ 1. 원본 파일 읽기                      │
│    docs/week1/deep-dive-llms/eng/index.md │
│    + docs/glossary.md                 │
│    + YouTube 여부 확인 (frontmatter)  │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 2. Task: terminology-lookup          │
│    subagent_type: general-purpose    │
│    원문에서 용어 추출 → 용어집 확인     │
│    → 없는 용어 웹검색 → JSON 결과      │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 3. Task: translator                  │
│    subagent_type: general-purpose    │
│    영어 원문 → 한국어 초벌 번역         │
│    용어 검색 결과 참조하여 번역         │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 4. Task: translation-refiner (1차)   │
│    subagent_type: general-purpose    │
│    번역체 → 자연스러운 한국어           │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 5. Task: translation-validator       │
│    subagent_type: general-purpose    │
│    원문 대비 검증 (누락, 오역)          │
│    → 수정 제안 JSON 생성               │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 6. Task: translation-refiner (2차)   │
│    validator 피드백 반영               │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 7. Task: translation-qa              │
│    subagent_type: general-purpose    │
│    최종 품질 검증 (문체, 용어, 가독성)  │
│    → QA 보고서 JSON 생성               │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 8. Task: translation-refiner (3차)   │
│    QA 피드백 반영 → 최종본             │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 9. [신규] 요약 생성 (조건부)           │
│    IF source_type == "youtube"       │
│       OR chapters 필드 존재           │
│       AND --skip-summary 아님        │
│    THEN Task: translation-summarizer │
│    ELSE 스킵                          │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 10. 마크다운 파일 조립 및 저장         │
│    - YouTube: 요약 + 전체 번역 조립    │
│    - 기타: 기존 형식 유지              │
└──────────────────────────────────────┘

중요: 한글 파일 편집 시 Edit 도구 사용 금지

Claude Code의 Edit 도구는 UTF-8 한글 문자(3바이트)를 처리할 때 바이트 경계 오류를 발생시킵니다.

CRITICAL: 한글이 포함된 파일을 수정할 때 절대 Edit 도구를 사용하지 마세요!
항상 Write 도구로 전체 파일을 다시 작성하세요.

이 규칙은 모든 단계에 적용됩니다:

• 번역 파일 생성: Write 사용
• 번역 파일 수정: Write 사용 (Edit 절대 금지)
• refiner/validator 피드백 반영: Write 사용

실행 지침

이 스킬이 호출되면 다음 단계를 따르세요:

Step 1: 파일 읽기

경로 파싱:
- 2단계 (week1/slug): 단일 페이지
- 3단계 (week1/parent/child): 자식 페이지

단일 페이지:
1. docs/week{N}/{slug}/eng/index.md 읽기 (원문)
2. docs/glossary.md 읽기 (용어집)
3. docs/week{N}/{slug}/kr/ 디렉토리 없으면 생성
4. frontmatter에서 source_type 또는 chapters 확인 → isYouTube 플래그 설정

자식 페이지:
1. docs/week{N}/{parent}/eng/{child}.md 읽기 (원문)
2. docs/glossary.md 읽기 (용어집)
3. docs/week{N}/{parent}/kr/ 디렉토리 없으면 생성
4. frontmatter에서 source_type 또는 chapters 확인 → isYouTube 플래그 설정

Step 2: Terminology Lookup 실행

Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/translate-reading/terminology-lookup.md 내용 + 원문 + 용어집
- description: "terminology lookup - 용어 검색"

용어집에 없는 기술 용어, 고유명사를 웹검색하여 번역 기준 수립

Step 3: Translator 실행

Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/translate-reading/translator.md 내용 + 원문 + 용어집 + 용어 검색 결과
- description: "translator - 초벌 번역"

Step 4: Refiner 1차 실행

Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/translate-reading/translation-refiner.md 내용 + 번역 결과
- description: "refiner 1차 - 번역체 정리"

Step 5: Validator 실행

Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/translate-reading/translation-validator.md 내용 + 원문 + 번역 결과
- description: "validator - 품질 검증"

Step 6: Refiner 2차 실행

Task tool 호출:
- prompt: refiner.md 내용 + 번역 결과 + validator 피드백
- description: "refiner 2차 - validator 피드백 반영"

Step 7: QA 실행 (--skip-qa가 아닌 경우)

Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/translate-reading/translation-qa.md 내용 + 번역 결과
- description: "QA - 최종 품질 검증"

QA 결과에서 scores 추출하여 저장:
qaScores = {
  consistency: N,
  readability: N,
  accuracy: N,
  overall: N
}

이 점수는 Step 10에서 frontmatter에 포함됩니다.

Step 8: Refiner 3차 실행

Task tool 호출:
- prompt: refiner.md 내용 + 번역 결과 + QA 피드백
- description: "refiner 3차 - QA 피드백 반영"

Step 9: Summarizer 실행 (YouTube 콘텐츠 + --skip-summary 아닌 경우)

조건 확인:
- isYouTube == true (source_type: "youtube" 또는 chapters 필드 존재)
- --skip-summary 옵션이 아님

조건 만족 시 Task tool 호출:
- subagent_type: "general-purpose"
- prompt: .claude/agents/translate-reading/translation-summarizer.md 내용
         + 번역된 마크다운 전체
         + 원본 마크다운 (챕터 구조 참조용)
- description: "summarizer - 챕터별 요약 생성"

출력: JSON 형식의 요약 데이터
{
  "tldr": "...",
  "learningGoals": [...],
  "chapters": [...],
  "totalChapters": N
}

Step 10: 파일 조립 및 저장

YouTube 콘텐츠 (요약 포함)

---
title: "한국어 제목"
originalTitle: "English Title"
author: "저자명"
sourceUrl: "원문 URL"
translatedAt: "YYYY-MM-DD"
status: "final"
contentType: "youtube"
duration: "3:31:05"
totalChapters: 24
hasSummary: true
qaScore:
  consistency: 8
  readability: 7
  accuracy: 9
  overall: 8
---

# 한국어 제목

[원본 영상](URL)

<!-- SUMMARY_START -->

## TL;DR

{tldr}

## 이 콘텐츠에서 배울 수 있는 것

{learningGoals를 불릿 리스트로}

---

## 챕터별 요약

### 1. {chapter.title} ({chapter.timestamp})

{chapter.summary}

**핵심 포인트:**
{chapter.keyPoints를 불릿 리스트로}

---

### 2. {다음 챕터}...

<!-- SUMMARY_END -->

---

<!-- FULL_TRANSLATION_START -->

## 전체 번역

### 목차

{번역된 목차 - 원본에서 가져옴}

---

{번역된 전체 본문 - Step 8의 결과물}

<!-- FULL_TRANSLATION_END -->

---

## 핵심 요약

{기존 핵심 요약 유지}

일반 콘텐츠 (기존 형식)

단일 페이지:
Write tool로 docs/week{N}/{slug}/kr/index.md 저장

자식 페이지:
Write tool로 docs/week{N}/{parent}/kr/{child}.md 저장

공통:
- 마크다운 형식
- 메타데이터 포함 (원문 URL, 번역일 등)
- qaScore 포함 (Step 7에서 추출한 점수)
- 기존 출력 형식 유지

일반 콘텐츠 frontmatter 예시:
---
title: "한국어 제목"
originalTitle: "English Title"
author: "저자명"
sourceUrl: "원문 URL"
translatedAt: "YYYY-MM-DD"
status: "final"
qaScore:
  consistency: 8
  readability: 7
  accuracy: 9
  overall: 8
---

옵션

--refine-only

이미 번역된 콘텐츠의 품질만 개선합니다.

• docs/week{N}/{slug}/kr/index.md 파일이 존재해야 함
• translator 단계 스킵
• refiner → validator → refiner → qa → refiner 만 실행

--skip-qa

QA 단계를 스킵합니다 (빠른 번역용).

• translator → refiner(1차) → validator → refiner(2차) 까지만 실행
• qaScore가 frontmatter에 포함되지 않음

--skip-summary

요약 단계를 스킵합니다.

• YouTube 콘텐츠에서도 요약 생성을 건너뜀
• 전체 번역만 포함된 기존 형식으로 저장

--all-chapters

YouTube 디렉토리의 모든 챕터를 순차적으로 번역합니다.

사용 조건:

• docs/week{N}/{slug}/eng/ 디렉토리가 존재해야 함
• 디렉토리 내에 챕터별 .md 파일이 있어야 함

동작:

1. eng/ 디렉토리 내 모든 .md 파일 목록 조회
2. _index.md 제외
3. 각 챕터 파일에 대해 순차적으로 번역 파이프라인 실행
4. 결과를 docs/week{N}/{slug}/kr/ 에 저장

워크플로우:

/translate-reading week1/deep-dive-llms --all-chapters
           │
           ▼
┌──────────────────────────────────────┐
│ 1. 디렉토리 검색                      │
│    docs/week1/deep-dive-llms/eng/*.md │
│    → 24개 파일 발견 (_index.md 제외)  │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 2. 출력 디렉토리 생성                 │
│    mkdir -p docs/week1/deep-dive-llms/kr/│
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 3. 각 챕터 순차 번역                  │
│    for each chapter in chapters:     │
│      translate(chapter) → kr/chapter │
│    (기존 번역 파이프라인 재사용)       │
└──────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────┐
│ 4. 완료 보고                          │
│    ✓ 24개 챕터 번역 완료              │
│    → docs/week1/deep-dive-llms/kr/   │
└──────────────────────────────────────┘

완료 메시지:

✅ 전체 챕터 번역 완료!

📁 출력 디렉토리: docs/week1/deep-dive-llms/kr/
📊 번역된 챕터: 24개

생성된 파일:
  - kr/introduction.md
  - kr/pretraining-data.md
  - kr/tokenization.md
  ... (21개 더)

다음 단계:
  /upload-reading week1/deep-dive-llms --all-chapters

Agent 파일

• .claude/agents/translate-reading/terminology-lookup.md
• .claude/agents/translate-reading/translator.md
• .claude/agents/translate-reading/translation-refiner.md
• .claude/agents/translate-reading/translation-validator.md
• .claude/agents/translate-reading/translation-qa.md
• .claude/agents/translate-reading/translation-summarizer.md (신규)

참고 문서

• PLAN-translate-skill.md: 번역 가이드라인 상세
• docs/glossary.md: 용어집

출력 형식

일반 콘텐츠

번역 완료된 마크다운 파일 구조:

---
title: "한국어 제목"
originalTitle: "English Title"
author: "저자명"
sourceUrl: "원문 URL"
translatedAt: "2025-01-07"
status: "final"
qaScore:
  consistency: 8
  readability: 7
  accuracy: 9
  overall: 8
---

# 한국어 제목

## 섹션 1

본문 내용...

## 섹션 2

본문 내용...

---

## 핵심 요약

- 포인트 1
- 포인트 2

YouTube 콘텐츠 (요약 포함)

---
title: "한국어 제목"
originalTitle: "English Title"
author: "저자명"
sourceUrl: "원문 URL"
translatedAt: "2025-01-07"
status: "final"
contentType: "youtube"
duration: "3:31:05"
totalChapters: 24
hasSummary: true
qaScore:
  consistency: 8
  readability: 7
  accuracy: 9
  overall: 8
---

# 한국어 제목

[원본 영상](URL)

<!-- SUMMARY_START -->

## TL;DR

전체 요약 내용...

## 이 콘텐츠에서 배울 수 있는 것

- 학습 목표 1
- 학습 목표 2

---

## 챕터별 요약

### 1. 소개 (0:00)

챕터 요약 내용...

**핵심 포인트:**
- 포인트 1
- 포인트 2

---

### 2. 다음 챕터 (1:00)

...

<!-- SUMMARY_END -->

---

<!-- FULL_TRANSLATION_START -->

## 전체 번역

### 목차

1. [소개](#1-소개) (0:00)
2. [다음 챕터](#2-다음-챕터) (1:00)
...

---

### 1. 소개

[0:00] 번역된 본문...

---

### 2. 다음 챕터

[1:00] 번역된 본문...

<!-- FULL_TRANSLATION_END -->

---

## 핵심 요약

- 포인트 1
- 포인트 2

구분자 용도

구분자	용도
<!-- SUMMARY_START -->	요약 섹션 시작 (파싱용)
<!-- SUMMARY_END -->	요약 섹션 끝
<!-- FULL_TRANSLATION_START -->	전체 번역 시작
<!-- FULL_TRANSLATION_END -->	전체 번역 끝

이 구분자는 향후 챕터별 페이지 분리 시 파싱에 활용됩니다.