Translate Article

Step 2: 카테고리 자동 판별

아티클 주제를 분석하여 TIL 카테고리를 자동 결정한다. 판별이 애매한 경우 사용자에게 질문한다.

카테고리 목록:

새 카테고리가 필요한 경우 사용자에게 확인 후 디렉토리를 생성한다.

Step 3: 번역 실행

핵심 원칙: 원문 구조 보존

이것이 이 스킬의 가장 중요한 원칙이다. 번역은 원문의 의미를 한국어로 전달하는 것이지, 문서를 재구성하는 것이 아니다.

하지 말 것 (CRITICAL)

❌ 원문에 없는 "결론부터 말하면" 섹션 추가
❌ 원문 구조를 TIL 형식으로 재구성
❌ 원문에 없는 내용 추가 또는 생략
❌ 섹션 순서 변경
❌ README.md 수정
❌ git add, git commit, git push 실행 (사용자가 명시적으로 요청하지 않는 한)

해야 할 것

✅ 원문의 이미지를 ![alt](url) 형태로 그대로 가져오기 (우선)
✅ 이미지 URL을 가져올 수 없는 경우에만 mermaid/테이블로 재현 (fallback)
✅ 기술 용어 첫 등장 시 영문 병기: "프롬프트 체이닝(Prompt Chaining)"
✅ 이후 등장 시에는 한국어 또는 영어 중 자연스러운 쪽 사용
✅ 코드/명령어는 번역하지 않고 원문 그대로 유지
✅ 번역 출처 헤더 추가 (아래 템플릿 참조)

다이어그램/이미지 처리 전략

원문 이미지를 우선 사용하고, 실패 시 mermaid로 fallback 한다.

1순위: 원문의 <img> / ![alt](url) 에서 이미지 URL 추출 → 그대로 삽입
2순위: 이미지 URL을 가져올 수 없거나 CDN 접근 불가 → mermaid로 재현

이미지 추출 방법:

• WebFetch로 원문 HTML을 가져올 때, 모든 <img> 태그의 src와 alt를 수집
• ![alt text](image_url) 형태로 원문의 해당 위치에 삽입
• alt text는 원문 그대로 유지 (번역하지 않음)

Step 4: 번역 규칙

4.1 언어 규칙

4.2 문체

• 문어체 사용 (~다, ~이다)
• 문단 단위 번역 (문장 단위 직역 금지)
• 자연스러운 한국어 흐름 유지
• 원문의 톤(격식/비격식)을 보존

4.3 불확실한 번역

• 의미가 불확실한 부분은 원문을 괄호로 병기
• 예: "이 방법은 포카요케(Poka-yoke, 실수 방지) 원칙을 적용한다"

Step 5: CLAUDE.md 포맷팅 규칙 적용

원문 구조를 보존하되, 아래 포맷팅 규칙은 반드시 따른다:

Bold 규칙

닫는 ** 다음에 반드시 띄어쓰기:

❌ Bad: **정식 지원(Stable)**된다.
✅ Good: **정식 지원(Stable)** 된다.

mermaid 규칙 (fallback 시에만 적용)

원문 이미지를 가져올 수 없어 mermaid로 재현하는 경우:

스타일: 어두운 배경 + 흰 글씨만 사용

✅ style Node fill:#1565C0,color:#fff

줄바꿈: <br> 사용 (\n 금지)

✅ ["첫째 줄<br>둘째 줄"]

subgraph: style 지정하지 않음 (기본 배경 사용)

권장 색상:

ASCII 박스 금지

원문에 ASCII 다이어그램이 있으면 테이블 또는 mermaid로 변환한다.

수식

원문에 수식이 있으면 LaTeX 문법으로 변환한다.

❌ Bad: S = 1 / ((1 - P) + P/N)
✅ Good: $S = \frac{1}{(1-P) + \frac{P}{N}}$

Step 6: 파일 저장

파일명 규칙

파일명 = 제목(한국어 번역)과 동일:

• 특수문자 제거, 공백을 하이픈(-)으로 변환
• 첫 줄은 반드시 # 로 시작

저장 위치

/Users/sskim/Library/Mobile Documents/iCloud~md~obsidian/Documents/Note/Sources/Translations/

번역본은 Obsidian vault의 Sources/Translations/ 아래에 평면(flat) 구조로 저장한다. 카테고리별 서브디렉토리를 만들지 않는다 — 파일명이 고유하면 Obsidian wikilink [[파일명]]이 위치 무관하게 해석되고, 분류는 frontmatter tags/topics로 충분하다.

Step 2에서 판별한 카테고리는 경로가 아니라 frontmatter 태그로 기록한다 (예: tags: [til, spring]).

번역 헤더 템플릿

파일 시작 부분에 아래 헤더를 추가:

# 번역된 제목

> 이 글은 [원문 사이트명]의 [원문 제목](원문 URL) 을 한국어로 번역한 글입니다.
> 원문 작성일: YYYY년 MM월 DD일 | 작성자: 저자명

• 원문 작성일/저자가 확인 불가능한 경우 해당 항목 생략
• 원문 제목은 영어 원문 그대로 사용

출처 섹션

문서 맨 마지막에 출처 추가:

## 출처

- [원문 제목 - 사이트명](URL) - 원문

Step 7: 완료 리포트

파일 저장 후 사용자에게 아래 정보를 안내한다:

• 저장 경로 (카테고리 포함)
• 원문 제목 → 번역 제목
• 이미지: 원문에서 가져온 수 / mermaid fallback 수

Step 8: Post-write linking (선택적)

번역 문서 저장 후, Obsidian Vault에서 같은 주제의 관련 노트를 검색한다.

VAULT="~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Note"
grep -rli "키워드" "$VAULT" --include="*.md" | head -5

관련 노트가 발견되면:

• 관련 노트의 related_notes 프로퍼티에 번역본 wikilink([[번역본-파일명]])를 제안 (사용자 확인 후 추가)
• 번역본이 vault 내부(Sources/Translations/{category}/)에 있으므로 wikilink가 Obsidian 그래프뷰·백링크에 자동 반영됨
• 관련 노트 목록을 완료 리포트에 포함

Step 9: Self-Check

파일 저장 후 아래 항목 점검:

• 원문 구조가 보존되었는가? (섹션 순서, heading 계층)
• 원문에 없는 내용을 추가하지 않았는가?
• 번역 헤더가 포함되었는가?
• 기술 용어가 적절히 병기되었는가?
• 코드 블록이 번역되지 않고 원문 그대로인가?
• 원문 이미지를 ![alt](url) 형태로 가져왔는가? (가져올 수 없는 경우만 mermaid)
• Bold 닫는 ** 다음에 띄어쓰기가 있는가?
• mermaid 사용 시: \n 대신 <br>, 어두운 배경 + color:#fff
• mermaid 사용 시: mcp__mermaid-mcp__validate_and_render_mermaid_diagram으로 렌더링 검증
• ASCII 박스 대신 테이블/mermaid를 사용했는가?
• 출처가 명시되었는가?
• 파일명이 번역된 제목과 일치하는가?
• Post-write linking 실행했는가? (Obsidian vault 사용 시)

Troubleshooting

주의사항

• README.md는 GitHub Actions가 자동 생성하므로 절대 수정하지 말 것
• git add, git commit, git push는 사용자가 명시적으로 요청할 때만 실행
• 원문에 없는 내용을 임의로 추가하지 말 것 (mermaid 다이어그램 재현은 예외)
• 번역 품질이 불확실한 부분은 원문을 병기하여 투명하게 처리