Skip to content

feat(i18n): add Korean (ko) localization across docs and web app#276

Open
meohyun2 wants to merge 1 commit into
shareAI-lab:mainfrom
meohyun2:feat/korean-localization
Open

feat(i18n): add Korean (ko) localization across docs and web app#276
meohyun2 wants to merge 1 commit into
shareAI-lab:mainfrom
meohyun2:feat/korean-localization

Conversation

@meohyun2
Copy link
Copy Markdown

Summary

Adds a full Korean translation layer across every i18n-enabled surface of the project.

  • Root README → new README-ko.md; existing README.md / README-zh.md / README-ja.md get [한국어](./README-ko.md) added to their cross-language headers.
  • Session docs → new docs/ko/ with full Korean translations of all 12 session docs (s01-s12). Replaces the previously empty docs/kr/ directory; ko matches ISO 639-1 and the existing en / zh / ja naming convention.
  • Web i18n → new web/src/i18n/messages/ko.json mirroring the en.json key tree.
  • Locale wiring"ko" registered in:
    • web/src/lib/i18n.tsx, web/src/lib/i18n-server.ts
    • web/src/app/[locale]/layout.tsx (locales, metaMessages)
    • web/src/components/layout/header.tsx (new 한국어 button)
    • web/src/types/agent-data.ts (DocContent.locale union)
    • web/scripts/extract-content.ts (localeDirs, detectLocale return type)
  • Generated dataweb/src/data/generated/{docs,versions}.json regenerated to include the 12 Korean docs, so the Next.js static export emits /ko/, /ko/timeline/, /ko/compare/, /ko/layers/, and /ko/s01..s12 (plus the /diff sub-routes).

Translation conventions

  • Tone: professional 존댓말 (formal-polite) — matches the style of Korean tech books / engineering blogs.
  • Widely-known technical terms are kept in English when the Korean dev community uses them in English, wrapped in natural Korean grammar:
    agent, harness, loop, tool, subagent, skill, context, compact, task, worktree, mailbox, FSM, JSONL, Bash, RLHF, GOFAI, …
  • First-mention glosses added in parentheses for terms a Korean reader may find unfamiliar — e.g.:
    • harness (하네스 — 모델을 감싸 실제 환경에서 동작하게 해주는 코드 레이어)
    • Agency (행위자성 — 인지·추론·행동의 능력)
    • FSM (Finite State Machine, 유한 상태 기계)
    • worktree (워크트리 — git worktree, 같은 저장소를 여러 디렉터리에 동시에 체크아웃하는 기능)
  • Code blocks, ASCII diagrams, file paths, function/variable names, URLs, and proper nouns are preserved verbatim.
  • Doc line counts match the English originals exactly (s01: 116, s02: 99, s03: 96, s04: 94, s05: 108, s06: 124, s07: 131, s08: 107, s09: 125, s10: 106, s11: 142, s12: 121) to keep the mental-model section structure aligned.

Verification (already run locally)

  • cd web && npm run extractFound 48 doc files across 4 locales, 48 docs
  • cd web && npx tsc --noEmit → 0 errors
  • cd web && npm run build → succeeds, emits /ko/* and /ko/sXX/* static routes alongside the existing locales
  • grep -c '"locale": "ko"' web/src/data/generated/docs.json12
  • head -1 README-ko.md[English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md) | [한국어](./README-ko.md)

Test plan

A full manual QA scenario lives at docs/ko/TEST_SCENARIOS.md. Highlights:

  • docs/kr/ removed; docs/ko/ contains 12 session docs + TEST_SCENARIOS.md
  • All 4 root READMEs carry the 4-language header row
  • npm run extract && npx tsc --noEmit && npm run build clean in web/
  • npm run dev → locale switcher shows EN | 中文 | 日本語 | 한국어 (desktop + mobile)
  • /ko, /ko/timeline, /ko/compare, /ko/layers, /ko/s01../ko/s12 all render with Korean UI strings
  • On /ko/sXX the Learn tab renders docs/ko/sXX-*.md content (Korean prose, English code preserved)
  • Regression: /en, /zh, /ja still render correctly
  • Dark mode toggle still works on /ko/*

Out of scope

  • agents/sXX_*.py source files (English identifiers / comments preserved; not user-facing i18n).
  • skills/*/SKILL.md (Anthropic Agent SDK style — no multi-language layer).
  • Config files (.env, requirements.txt, package.json).

🤖 Generated with Claude Code

Adds a full Korean translation layer covering every i18n-enabled
surface of the project:

- README-ko.md at repo root, with the cross-language header updated on
  README.md / README-zh.md / README-ja.md to include 한국어.
- docs/ko/ with full Korean translations of all 12 session docs
  (s01-s12) plus TEST_SCENARIOS.md. Replaces the previously empty
  docs/kr/ directory; ko matches ISO 639-1 and the existing en/zh/ja
  naming convention.
- web/src/i18n/messages/ko.json mirroring the en.json key tree.
- Wires "ko" into the i18n plumbing: lib/i18n.tsx, lib/i18n-server.ts,
  app/[locale]/layout.tsx, components/layout/header.tsx (한국어 button),
  types/agent-data.ts (DocContent.locale), and
  scripts/extract-content.ts (localeDirs + detectLocale return type).
- Regenerated web/src/data/generated/{docs,versions}.json so the Next.js
  build emits /ko/* static routes (verified: /ko, /ko/timeline,
  /ko/compare, /ko/layers, /ko/s01../ko/s12, /ko/sXX/diff).

Translation conventions: formal-polite (존댓말) tone; widely-known
technical terms (agent, harness, loop, tool, subagent, skill, task,
worktree, mailbox, FSM, JSONL) kept as English wrapped in Korean
grammar; first-mention glosses in parentheses for terms a Korean reader
may find unfamiliar (harness, Agency, GOFAI, RLHF, JSONL, FSM,
worktree, daemon thread, dependency graph, etc.).

Doc line counts match the English originals exactly to keep the
mental-model structure aligned (Problem / Solution / How It Works /
Key Insight / Why This Matters / What's Next).

See docs/ko/TEST_SCENARIOS.md for the manual QA plan.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@vercel
Copy link
Copy Markdown

vercel Bot commented May 11, 2026

@meohyun2 is attempting to deploy a commit to the crazyboym's projects Team on Vercel.

A member of the Team first needs to authorize it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant