ADR KR/EN 번역 누락분 일괄 보강 (블로그 게시 ADR 양면 완전화)

목표

• Sprint 157 P10 (콘텐츠 i18n 인프라)에서 도입한 docs/adr-en/ 구조에 실제 영문판 콘텐츠를 채워 EN coverage 1/106 (0.9%) → 106/106 (100%) 달성
• Scribe 직접 번역 방식으로 API key 의존 제거 (scripts/translate-adr.mjs 미사용)
• Sprint 157 시드 #25 (check-adr-en-coverage --strict CI hard gate) 정착으로 회귀 자동 차단
• 사용자 직접 지적 → 즉시 hotfix 사이클(Sprint 157 패턴 계승)로 UI i18n 매칭 누락 4건 보강

결정

• 번역 방식: 사용자 옵션 확정 — translate-adr.mjs (Claude API, ANTHROPIC_API_KEY 필요) 미사용, Scribe Agent 직접 번역. Claude 세션 자체가 번역 능력을 가지므로 API key 우회 + 비용 0
• batch 분할 (Phase B 95개): 3 병렬 Agent로 분할 (B-1: sprint-4087-plan 30개 / B-2: sprint-91127 37개 / B-3: sprint-128~155 28개) — 단일 Agent 컨텍스트 부담 분산 + 시간 단축
• Phase 분리: Phase A (시범 10개 — 영구 8 + sprint-156 + topics/sprint-95) → 검증 → Phase B (전체 95개) → Phase C (CI gate). 시범 단계의 품질 확인 후 전체 batch 진행으로 위험 최소화
• CI hard gate 동시 활성화 (시드 #25 정착): Phase B에서 100% 도달 후 즉시 --strict step을 quality-docs job에 추가 → 신규 ADR EN 누락 시 CI fail로 회귀 자동 차단
• 번역 정책: docs/adr-en/README.md 정책 준수 — frontmatter 보존(title만 영문화), 기술 용어(Outbox/Saga/MSA/Gateway 등) 영문 유지, 코드블록/PR 링크/파일 경로/sprint 슬러그 100% 보존, mermaid 노드 라벨만 번역
• 의도적 한국어 보존 허용: i18n bilingual reference 테이블, KR 블로그 원문 인용(sprint-100), regex 패턴(주차/월), accessibility 라벨 예시(일요일), 코드 리터럴('알림'/'분류' 등), API 쿼리 예시(query=입문)는 의도적 보존 — 9 EN sprint pages에 잔존

구현 (2 PR squash merge, origin/main 1ba57d6 → a73c596)

PR #269 세부 (Phase A/B/C)

Phase A — 영구 8 + 토픽 1 + sprint-156 = 10개 (commit 22b7cc5, +1,292):

• 영구 ADR 8개: ADR-001 (Gateway → Identity DB Separation), ADR-002 (Outbox Pattern), ADR-003 (Redis/RabbitMQ ACL), ADR-024 (Admin Server-side Guard), ADR-025 (Gateway OAuth Error Normalization), ADR-026 (Stuck Rollouts & Sealed Secrets Debt), ADR-027 (Aether GitOps Branch Discipline), ADR-028 (Dev Cluster Separation)
• 스프린트 1개: sprint-156 (Sprint 150 미해소 자동화 부채 3건 묶음)
• 토픽 1개: topics/sprint-95-programmers-dataset
• 2 병렬 Agent (영구 8 / 스프린트+토픽 2)

Phase B — 스프린트 95개 (commit 86734c9, +13,643):

• B-1 (30): sprint-40, 48, 51, 6271, 7287, 87-plan
• B-2 (37): sprint-9199 (프로그래머스 이전), 100127 (CI 리팩토링)
• B-3 (28): sprint-128~155 (안전망 + 최근)
• 3 병렬 Agent 동시 실행 — 단일 세션 컨텍스트 부담 분산

Phase C — CI hard gate (commit 0509d91, +4 −1):

• .github/workflows/ci.yml quality-docs job에 step 추가:
  YAML복사

  - name: Check ADR EN coverage (strict)
    run: node scripts/check-adr-en-coverage.mjs --strict
  

• detect-changes paths filter에 scripts/check-adr-en-coverage.mjs 추가
• docs/adr-en/README.md coverage tracking 섹션 갱신 (advisory → hard gate)

PR #270 세부 (hotfix UI i18n)

사용자 직접 지적: "영문번역본이 매칭이 안되어있는거같은데?" → 빌드 산출물 분석으로 4지점 발견:

1. blog/src/app/(adr)/layout.tsx — 메타 description 하드코딩 한국어 → 영문 단일화
   • "AlgoSu 프로젝트의 아키텍처 결정 기록" → "architecture decisions and sprint retrospectives"
2. blog/src/components/locale-toggle.tsx — aria-label/title 비대칭 (EN 페이지에서 KR 노출, KR 페이지에서 EN 노출)
   • 수정: isEn ? 'Switch to Korean' : '영어로 전환' (각 locale에서 자국어)
3. blog/src/components/blog/code-block.tsx — copy 버튼 "코드 복사"/"복사"/"복사됨" 한국어 하드코딩
   • 수정: usePathname() 기반 locale 감지 → t(locale, ...) 적용
4. blog/src/lib/i18n.ts — codeBlockCopy/Copied/CopyAriaLabel keys 추가 (KR/EN)

효과: EN sprint pages 한국어 잔재 96 → 9 (남은 9건 모두 ADR 본문의 의도적 보존)

검증

• 4 PR (#269 Phase A/B/C + #270 hotfix) 모두 CI fail 0, mergeStateStatus CLEAN ✅
• node scripts/check-adr-en-coverage.mjs --strict → 106/106 (100.0%) exit 0 ✅
• node scripts/check-adr-links.mjs blog/out/adr → 108 HTML, 1,125 links, 0 broken ✅
• node scripts/check-adr-links.mjs blog/out/en/adr → 108 HTML, 1,125 links, 0 broken ✅
• node scripts/check-doc-refs.mjs → 279 files, 0 broken refs ✅
• npm run build (blog) → 240 정적 페이지 (KR 108 + EN 108 ADR pages + 24 posts) ✅
• 한국어 잔재 grep: 이전 96 EN sprint pages → 9 (모두 의도적 보존)
• 의도적 보존 9 페이지 1건씩 정밀 검증: 블로그 KR 원문 인용 / i18n bilingual 매핑 / regex 패턴 / accessibility 라벨 / 코드 리터럴 / API 쿼리 예시 — 번역 누락 0건

브랜치 규율 ✅

• 3 PR 모두 신규 브랜치 + Squash merge — 26 스프린트 연속 준수 (Sprint 134 위반 이후)
• main 직접 commit 0건
• 작업 브랜치: feat/sprint-158-adr-en-batch (#269), fix/sprint-158-ui-i18n-hotfix (#270)

신규 패턴

1. Scribe 직접 번역 + 병렬 batch 분할 패턴 — API key 의존 제거. 105개 ADR을 5개 Scribe Agent (영구 8 / 스프린트+토픽 2 / sprint-4087 30 / sprint-91127 37 / sprint-128~155 28)로 병렬 처리. translate-adr.mjs 인프라 미사용으로 비용 0, Sprint 157 시드 #19 콘텐츠 정착 단계의 대규모 batch 모델
2. 사용자 지적 → 즉시 빌드 산출물 분석 → 정확 진단 → hotfix 사이클 — "영문번역본이 매칭 안 됨" 지적에서 빌드된 EN HTML grep으로 한국어 잔재 위치 정확 파악(코드 line 단위). description/LocaleToggle/code-block 3개 컴포넌트 정확히 식별 → 4 commit 단일 PR. 추측 사이클 회피(Sprint 157 probe 패턴 직접 계승)
3. CI hard gate 동시 활성화 (Phase B 100% 도달 직후) — 인프라 정착 → 콘텐츠 채움 → 회귀 차단을 단일 sprint 내 완결. Sprint 157의 advisory(WARN) → Sprint 158의 strict(FAIL) 전환을 콘텐츠 100% 시점에 안전하게 진행. "측정 → 강화" 순서 패턴(Sprint 156 옵션 A 패턴 계승)
4. 본문 잔존 한국어를 9건 페이지별 1건씩 정밀 검증 — 일괄 "한국어 잔재 = 결함" 분류 회피. i18n 코드 리터럴/블로그 원문 인용/regex 설명/accessibility 라벨은 의도적 보존이므로 별도 분류. 정밀 검증 결과 번역 누락 0건 확인
5. 메타 description vs UI 텍스트 vs 본문 텍스트 — 3계층 i18n 누락 분리 — Phase C로 본문(docs/adr-en/*.md) 100% 매칭 완료 후, UI 매칭(description/LocaleToggle/code-block)이 별개 결함으로 노출. 사용자 검증 사이클에서만 회수됨. Sprint 159 시드 #30 후보: "i18n 매칭 체크리스트 3계층 (메타/UI/본문) 분리"