ADR KR/EN Translation Gap Bulk Backfill (Blog-Published ADR Bilingual Completion)

SummaryBackfill actual EN content into the docs/adr-en/ structure introduced by Sprint 157 P10 (content i18n infrastructure), raising EN coverage 1/106 (0.9%) → 106/106 (100%)

Date
ImpactCritical
PRs2
Lines changed+14959 -6

Implementation Phases

Phase A/B/C (3 commits)
#269

Phase A/B/C (3 commits)

scribe×4 + architect+14,939
hotfix UI i18n
#270

hotfix UI i18n

architect+20 −6

Key Decisions

Translation method

User-confirmed option — skip translate-adr.mjs (Claude API, requires ANTHROPIC_API_KEY), use Scribe Agent direct translation instead. Claude session has native translation capability → bypasses API key requirement + zero cost

Batch split (Phase B 95 files)

3 parallel Agents (B-1: sprint-40~87-plan 30 / B-2: sprint-91~127 37 / B-3: sprint-128~155 28) — distributes single-Agent context burden + reduces wall-clock time

Phase separation

Phase A (pilot 10 — permanent 8 + sprint-156 + topics/sprint-95) → verification → Phase B (full 95) → Phase C (CI gate). Risk minimization through pilot quality check before full batch

Simultaneous CI hard gate activation (seed #25 settlement)

Immediately after Phase B reaches 100%, added --strict step to quality-docs job → new ADR EN omissions blocked automatically via CI fail

Translation policy

Compliance with docs/adr-en/README.md policy — preserve frontmatter (translate only title), keep technical terms in English (Outbox/Saga/MSA/Gateway etc.), preserve code blocks/PR links/file paths/sprint slugs 100%, translate only mermaid node labels

Intentional Korean preservation allowed

i18n bilingual reference tables, KR blog body quotations (sprint-100), regex patterns (주차/월), accessibility label examples (일요일), code literals ('알림'/'분류' etc.), API query examples (query=입문) — 9 EN sprint pages retain intentional Korean

Goals

  • Backfill actual EN content into the docs/adr-en/ structure introduced by Sprint 157 P10 (content i18n infrastructure), raising EN coverage 1/106 (0.9%) → 106/106 (100%)
  • Eliminate API key dependency via Scribe direct translation (no scripts/translate-adr.mjs)
  • Establish Sprint 157 seed #25 (check-adr-en-coverage --strict CI hard gate) for automatic regression prevention
  • Address user direct feedback → immediate hotfix cycle (Sprint 157 pattern inheritance) to fix 4 UI i18n mapping gaps

Decisions

  • Translation method: User-confirmed option — skip translate-adr.mjs (Claude API, requires ANTHROPIC_API_KEY), use Scribe Agent direct translation instead. Claude session has native translation capability → bypasses API key requirement + zero cost
  • Batch split (Phase B 95 files): 3 parallel Agents (B-1: sprint-4087-plan 30 / B-2: sprint-91127 37 / B-3: sprint-128~155 28) — distributes single-Agent context burden + reduces wall-clock time
  • Phase separation: Phase A (pilot 10 — permanent 8 + sprint-156 + topics/sprint-95) → verification → Phase B (full 95) → Phase C (CI gate). Risk minimization through pilot quality check before full batch
  • Simultaneous CI hard gate activation (seed #25 settlement): Immediately after Phase B reaches 100%, added --strict step to quality-docs job → new ADR EN omissions blocked automatically via CI fail
  • Translation policy: Compliance with docs/adr-en/README.md policy — preserve frontmatter (translate only title), keep technical terms in English (Outbox/Saga/MSA/Gateway etc.), preserve code blocks/PR links/file paths/sprint slugs 100%, translate only mermaid node labels
  • Intentional Korean preservation allowed: i18n bilingual reference tables, KR blog body quotations (sprint-100), regex patterns (주차/월), accessibility label examples (일요일), code literals ('알림'/'분류' etc.), API query examples (query=입문) — 9 EN sprint pages retain intentional Korean

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

PR #269 Details (Phase A/B/C)

Phase A — Permanent 8 + topic 1 + sprint-156 = 10 files (commit 22b7cc5, +1,292):

  • Permanent ADRs (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)
  • Sprint (1): sprint-156 (Sprint 150 Unresolved Automation Debt 3-Item Batch)
  • Topic (1): topics/sprint-95-programmers-dataset
  • 2 parallel Agents (permanent 8 / sprint+topic 2)

Phase B — Sprint 95 files (commit 86734c9, +13,643):

  • B-1 (30): sprint-40, 48, 51, 6271, 7287, 87-plan
  • B-2 (37): sprint-9199 (Programmers migration), 100127 (CI refactoring)
  • B-3 (28): sprint-128~155 (safety net + recent)
  • 3 parallel Agents simultaneous execution — distributes single-session context burden

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

  • .github/workflows/ci.yml quality-docs job step added:
    YAML
    - name: Check ADR EN coverage (strict)
  run: node scripts/check-adr-en-coverage.mjs --strict
  • Added scripts/check-adr-en-coverage.mjs to detect-changes paths filter
  • Updated docs/adr-en/README.md coverage tracking section (advisory → hard gate)

PR #270 Details (hotfix UI i18n)

Direct user feedback: "the English translation doesn't seem to match" → build output analysis discovered 4 locations:

  1. blog/src/app/(adr)/layout.tsx — Korean description hardcoded → English-only
    • "AlgoSu 프로젝트의 아키텍처 결정 기록" → "architecture decisions and sprint retrospectives"
  2. blog/src/components/locale-toggle.tsx — aria-label/title asymmetry (KR shown on EN pages, EN shown on KR pages)
    • Fix: isEn ? 'Switch to Korean' : '영어로 전환' (native language per locale)
  3. blog/src/components/blog/code-block.tsx — copy button "코드 복사"/"복사"/"복사됨" Korean hardcoded
    • Fix: usePathname()-based locale detection → t(locale, ...) applied
  4. blog/src/lib/i18n.ts — codeBlockCopy/Copied/CopyAriaLabel keys added (KR/EN)

Effect: EN sprint pages Korean leakage 96 → 9 (remaining 9 all intentional preservation in ADR content)

Verification

  • All 4 PR commits (#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 static pages (KR 108 + EN 108 ADR pages + 24 posts) ✅
  • Korean leak grep: 96 EN sprint pages → 9 (all intentional preservation)
  • Per-page precise verification of 9 intentional preservation cases: blog KR original quotation / i18n bilingual mapping / regex patterns / accessibility labels / code literals / API query examples — 0 translation omissions

Branch Discipline ✅

  • All 3 PRs created on new branches + Squash merge — 26 sprint consecutive compliance (since Sprint 134 violation)
  • 0 direct main commits
  • Work branches: feat/sprint-158-adr-en-batch (#269), fix/sprint-158-ui-i18n-hotfix (#270)

New Patterns

  1. Scribe direct translation + parallel batch split pattern — Eliminates API key dependency. 105 ADRs processed by 5 Scribe Agents in parallel (permanent 8 / sprint+topic 2 / sprint-4087 30 / sprint-91127 37 / sprint-128~155 28). Skipped translate-adr.mjs infrastructure → zero cost. Large-scale batch model for Sprint 157 seed #19 content settlement
  2. User feedback → immediate build output analysis → precise diagnosis → hotfix cycle — From "EN translation not matching" feedback, accurately located Korean leak positions via build EN HTML grep (per code line). Identified 3 components (description/LocaleToggle/code-block) precisely → 4 commits in single PR. Avoids guessing cycle (Sprint 157 probe pattern direct inheritance)
  3. Simultaneous CI hard gate activation (right after Phase B 100% reach) — Infrastructure settlement → content filling → regression blocking completed within single sprint. Sprint 157's advisory (WARN) → Sprint 158's strict (FAIL) transition safely executed at the 100% content moment. "Measure → strengthen" pattern (Sprint 156 option A pattern inheritance)
  4. Per-page precise verification of 9 retained Korean cases — Avoids bulk "Korean = defect" classification. i18n code literals / blog quotations / regex explanations / accessibility labels are intentional preservation and classified separately. Precise verification result: 0 translation omissions
  5. Meta description vs UI text vs body text — 3-layer i18n gap separation — Phase C completed body (docs/adr-en/*.md) 100% matching, but UI matching (description/LocaleToggle/code-block) revealed as separate defect. Caught only by user verification cycle. Sprint 159 seed #31 candidate: "i18n matching checklist 3-layer (meta/UI/body) separation"