feat: add internationalization message platform

merge: design system platform
2026-07-26 16:17:39 +09:00 · 2026-07-26 15:49:13 +09:00
57 changed files with 1711 additions and 201 deletions
@@ -82,7 +82,9 @@
        { "script": "check:types:fixture:async-overlay", "expect": "fail" },
        { "script": "check:types:fixture:route-runtime", "expect": "fail" },
        { "script": "check:types:fixture:page-action", "expect": "fail" },
-        { "script": "check:types:fixture:icon-button", "expect": "fail" }
+        { "script": "check:types:fixture:icon-button", "expect": "fail" },
        { "script": "check:types:fixture:i18n-key", "expect": "fail" },
        { "script": "check:types:fixture:i18n-params", "expect": "fail" }
      ],
      "logPath": "artifacts/quality/check-types.txt",
      "evidence": ["artifacts/quality/check-types.txt"],
@@ -154,6 +156,8 @@
        { "script": "check:architecture", "expect": "pass" },
        { "script": "check:design-system", "expect": "pass" },
        { "script": "check:design-system:fixture", "expect": "fail" },
        { "script": "check:i18n", "expect": "pass" },
        { "script": "check:i18n:fixture", "expect": "fail" },
        { "script": "check:registries", "expect": "pass" },
        { "script": "check:registries:fixture", "expect": "fail" },
        { "script": "check:routes:fixture", "expect": "fail" }
@@ -163,6 +167,8 @@
        "artifacts/quality/dependency-report.json",
        "artifacts/quality/design-system.json",
        "artifacts/quality/design-system-fixture.json",
        "artifacts/quality/i18n.json",
        "artifacts/quality/i18n-fixture.json",
        "artifacts/quality/registries.json",
        "artifacts/quality/registry-fixture.json",
        "artifacts/quality/route-registry-fixture.json"
@@ -0,0 +1,96 @@
 # VD-06: Intl과 typed local message catalog
 - 상태: Accepted
 - 결정일: 2026-07-26
 - 적용 브랜치: `feature-frontend-i18n-message-formatting-contract`
 - 재검토: 승인 locale·복수형 문법·번역 추출 workflow가 local catalog 범위를 넘을 때
 ## 배경
 공통 셸, route surface, async/form 상태와 디자인 시스템 기본 문구가 JSX와
 JavaScript에 분산돼 있었다. 날짜는 일부 application mapper에서 고정 locale로
 가공되어 presentation이 locale을 바꿀 수 없었고, direction·누락 key·보간 실패
 정책도 없었다. 반면 현재 skeleton에는 번역 관리 서비스, 실제 번역 승인 절차,
 복잡한 ICU 문법이라는 제품 요구가 아직 없다. 이 단계에서 i18n vendor를 기본
 번들에 넣으면 소비 프로젝트가 제거하거나 다시 감싸야 할 의존성만 늘어난다.
 ## 결정
 1. 표준 `Intl.DateTimeFormat`, `NumberFormat`, `RelativeTimeFormat`,
   `ListFormat`, `PluralRules`와 typed local catalog를 기본 엔진으로 사용한다.
 2. `MessageKey`는 한국어 canonical catalog에서 도출하며 영어와 RTL smoke
   catalog는 `satisfies Record<MessageKey, string>`으로 compile-time parity를
   강제한다.
 3. 보간이 필요한 key는 `MessageParameters`에 key별 parameter object를
   선언한다. 잘못된 key, 누락·초과 parameter는 TypeScript negative fixture가
   거절한다.
 4. 기본 locale은 `ko-KR`, fallback locale도 `ko-KR`이다. 알려지지 않은 locale은
   language fallback 후 `ko-KR`로 정규화한다. 알려지지 않은 key와 누락 보간은
   raw key나 외부 값을 출력하지 않고 안전한 공통 fallback을 반환한다.
 5. `en-XA`는 영어 문구를 확장·accent 처리하는 pseudo locale이고 `ar-EG`는
   RTL 동작 smoke locale이다. 이 두 locale은 실제 제품 번역 완료를 의미하지
   않는다.
 6. 날짜 formatter의 기본 timezone은 테스트와 SSR/브라우저 결과가 흔들리지
   않도록 `UTC`다. 제품 timezone이 필요하면 호출자가 명시한다. invalid
   date/number/timezone은 `—`를 반환하고 throw하지 않는다.
 7. locale state는 React inbound concern이다. `LocaleProvider`가 copy,
   formatter와 `<html lang/dir>`을 제공하며 application/domain은 미리 번역된
   문자열 대신 의미 값과 timestamp를 반환한다.
 8. backend `message`, raw HTML, stack과 내부 key를 catalog 입력으로 신뢰하지
   않는다. transport/application failure kind를 등록된 사용자 message key로
   매핑한 뒤 presentation이 해석한다.
 9. key rename은 즉시 제거하지 않고 `MESSAGE_KEY_ALIASES`에 compatibility alias를
   둔다. alias는 새 호출의 타입에 포함하지 않아 신규 코드는 canonical key만
   사용한다.
 10. extraction, ICU rich message, 번역 SaaS 또는 framework adapter가 필요해지면
    `presentation/i18n` public API 뒤에서 교체한다. vendor type은 feature와
    design-system public prop으로 노출하지 않는다.
 ## 실행 경계
 ```text
 route/form/failure 의미 값
  -> presentation message key
  -> LocaleProvider
  -> typed catalog / Intl formatter
  -> text node와 accessible name
 ```
 - canonical catalog: `src/presentation/i18n/catalog.ts`
 - feature contribution: `src/features/*/contracts/*-message-catalog.js`를
  `src/features/installed-feature-messages.js`에서 조립
 - key/보간/fallback/alias: `message-contract.ts`
 - locale-safe value formatting: `formatters.ts`
 - React composition과 document metadata: `locale-provider.tsx`
 - public entry: `src/presentation/i18n/index.ts`
 ## 검증
 - `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
  backend message JSX 렌더링과 raw HTML 사용을 검사한다.
 - `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
 - type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
 - unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
  list/plural/select의 결정성을 검증한다.
 - component test는 document `lang/dir`, RTL Tabs와 direction-aware pagination,
  Drawer semantics를 검증한다.
 - Playwright는 320px pseudo reflow와 RTL compact shell/Drawer/focus restore를
  Chromium, Firefox, WebKit project에서 실행한다.
 ## 한계와 재검토 조건
 현재 catalog는 실제 번역 승인, ICU rich text, locale별 plural 문장 전체 조합,
 메시지 추출/번역 메모리와 서버 locale negotiation을 제공하지 않는다. 다음 중
 하나가 확인되면 별도 ADR로 엔진을 재평가한다.
 - 세 개 이상의 실제 승인 locale과 번역 담당 workflow
 - 복수형·성별·select가 한 문장 안에서 중첩되는 제품 copy
 - server/client extraction, namespace lazy-loading 또는 번역 SaaS 연동
 - SSR locale negotiation과 hydration 일치가 필요한 rendering mode
 ## Rollback
 `ko-KR` catalog가 기존 기본 문구를 보존하므로 provider를 고정 locale adapter로
 되돌려도 기본 UX를 유지한다. formatter/vendor 교체 시 public `message`,
 `date`, `number`, `relativeTime`, `list`, `plural`, `select` 계약과 negative
 fixture는 유지한다. alias는 migration window 종료 근거 없이 제거하지 않는다.
@@ -12,7 +12,7 @@
 - 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다.
 - 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다.
-최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-04 구현 결과를 이 문서에
+최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-08 구현 결과를 이 문서에
 누적 반영했다. 이후 구현으로 경로나 세부 내용이 달라질 수 있으므로, 각 항목은
 문서의 경로뿐 아니라 해당 테스트와 아키텍처 게이트로 계속 검증해야 한다.
@@ -33,13 +33,14 @@
 특히 다음은 선행 해결이 필요하다.
-RP-01~RP-05에서 TypeScript 도구 안전망, application runtime 주입,
+RP-01~RP-08에서 TypeScript 도구 안전망, application runtime 주입,
 query/mutation inbound adapter, HTTP 실행 계약과 executable route/release
-recovery 계약, 제거 가능한 reference 수직 슬라이스는 구현됐다. 현재 선행 해결
+recovery 계약, 제거 가능한 reference 수직 슬라이스, form/page, design system과
 i18n 실행 경계는 구현됐다. 현재 선행 해결
 대상은 다음과 같다.
-1. 폼, 페이지 템플릿, 확장된 디자인 시스템과 컴포넌트 워크벤치
+1. diagnostics/telemetry 실제 producer 연결
-2. 국제화, diagnostics, optional adapter recipe와 심화 품질 게이트
+2. registry evidence, 공급망과 optional adapter recipe 심화 게이트
 따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다.
 더 정확한 표현은 다음과 같다.
@@ -73,13 +74,13 @@ recovery 계약, 제거 가능한 reference 수직 슬라이스는 구현됐다.
 | 클라이언트 상태 | 부분 준비 | local state, theme context, session external store | 상태 소유권 표와 typed external-store 예제 |
 | 범용 global store | 프로젝트 선택 | 별도 라이브러리 없음 | 필요 조건에 따라 Zustand/Redux Toolkit/state machine 선택 |
 | 라우팅 | 준비됨 | Data Router, typed runtime map, codec, metadata consumer, bounded chunk recovery | reference feature route와 release E2E로 사용 범위 확장 |
-| 앱 셸·반응형 | 준비됨 | native modal Drawer, compact/desktop layout, Escape/link dismiss와 focus restore | RP-08에서 RTL/direction 검증 |
+| 앱 셸·반응형 | 준비됨 | native modal Drawer, compact/desktop layout, Escape/link dismiss/focus restore, pseudo reflow와 RTL direction | compact browser matrix 유지 |
 | 페이지 템플릿 | 준비됨 | Standard/Collection/Detail/Form/Status와 public design-system entry | feature별 slot 조합 유지 |
 | 디자인 토큰 | 준비됨 | primitive/semantic/component CSS, 48-token 자동 계약, dark/forced-colors/reduced-motion | 제품 brand token은 외부 프로젝트에서 확장 |
 | 공통 UI | 준비됨 | action/form/feedback/overlay/navigation primitive와 pattern, compatibility export | Storybook/visual은 RP-10 |
 | 아이콘 | 준비됨 | Lucide static vendor facade와 semantic icon/IconButton 접근성 계약 | 의미 icon 추가 시 bundle/접근성 기준 적용 |
 | 폼 | 준비됨 | Zod 기반 local facade, error summary/focus, 422 allowlist, dirty/pending/conflict 정책 | 복합 form 요구가 생기면 VD-04 조건으로 vendor adapter 평가 |
-| 국제화 | 미제공 | 한국어 문자열·locale이 하드코딩 | typed message/formatter/locale/RTL 경계 |
+| 국제화 | 준비됨 | 137-key typed catalog, locale provider, Intl formatter, safe fallback/alias, pseudo·RTL gate | 실제 locale·번역 승인은 프로젝트에서 연결 |
 | logging/diagnostics | 미제공 | telemetry port는 있으나 logger 없음 | redaction이 적용된 diagnostics/logging 경계 |
 | telemetry | 부분 준비 | registry, queue, redaction 존재 | HTTP·boot·cache·storage·route 사건에 실제 연결 |
 | 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 |
@@ -250,6 +251,24 @@ known vulnerability, license policy, SBOM/provenance를 pinned tool로 검사해
 - registry/compatibility의 실제 diff와 orphan reference 검사
 - transitive vulnerability, license, SBOM/provenance 공급망 gate
 #### RP-08에서 국제화 실행 경계 구현
 `src/presentation/i18n`은 shell, route, async/form error, page template와
 design-system 기본 copy의 canonical 경계다. `MessageKey`와 key별
 `MessageParameters`가 잘못된 key/보간을 compile time에 막고, runtime
 `resolveMessage`는 unknown locale/key와 누락 보간에서 raw 값 대신 안전한
 fallback을 반환한다. application mapper는 locale-formatted date를 반환하지
 않고 timestamp를 유지하며 presentation formatter가 `UTC` 또는 명시 timezone을
 적용한다.
 `LocaleProvider`는 `ko-KR`, `en-US`, `en-XA`, `ar-EG` smoke set과 document
 `lang/dir`을 동기화한다. `en-XA`는 긴 문구 reflow, `ar-EG`는 logical CSS,
 Drawer, Tabs arrow와 pagination 방향 icon을 검증하기 위한 개발 locale이다.
 실제 아랍어 번역 완료를 뜻하지 않는다. `check:i18n`과 negative fixture는 common
 UI literal, backend raw message render와 raw HTML interpolation을 거절한다.
 새 key rename은 canonical type에는 넣지 않고 runtime alias/migration window로
 호환한다.
 ### 5.3 P2: 경계와 recipe를 제공할 선택 항목
 다음 기능을 모든 앱의 초기 번들에 설치할 필요는 없다. 대신 port 또는 local
@@ -651,6 +651,26 @@ token rename은 alias/migration 기간을 두고, vendor adapter와 local API co
 RP-08은 기존 기본 언어 catalog를 fallback으로 유지한다. 번역 catalog를
 파괴적으로 덮어쓰지 않는다.
 **구현 증거 (2026-07-26)**
 - VD-06에서 dependency를 추가하지 않는 browser `Intl` + typed local catalog를
  채택하고 vendor 재평가 조건, fallback과 key migration 정책을 문서화했다.
 - `src/presentation/i18n`이 137개 common key, key별 interpolation,
  `ko-KR` fallback, compatibility alias, date/number/relative/list/plural/select
  formatter와 `LocaleProvider`를 제공한다.
 - shell, route lifecycle/access/recovery, async/form error, page template와
  design-system default copy가 catalog consumer로 연결됐다.
 - feature route copy는 feature-owned catalog contribution으로 분리되어 reference
  feature 제거 시 source와 built artifact에 전용 message key가 남지 않는다.
 - reference application mapper는 locale-formatted date 대신 timestamp를
  반환하고 presentation formatter가 UTC 또는 명시 timezone을 적용한다.
 - `check:i18n`과 type negative fixture가 catalog/placeholder 불일치,
  hardcoded common literal, backend raw message render, unsafe HTML,
  unknown key와 interpolation mismatch를 거절한다.
 - unit/component/browser test가 safe fallback, pseudo 320px reflow,
  document `lang/dir`, RTL Drawer/Tabs/directional icon과 deterministic formatter를
  검증한다.
 ### 09. `feature-frontend-diagnostics-telemetry-runtime`
 **목표**
@@ -178,6 +178,15 @@ template public API이며 feature와 shell은 이 entry만 소비한다. Lucide
 port가 아니다. native Dialog/Drawer/Menu/Tabs의 focus·keyboard 상태도
 presentation이 소유하고 use case나 outbound adapter로 올리지 않는다.
 RP-08에서 i18n은 application output port가 아니라 React inbound adapter의
 local facade로 확정됐다. domain/application은 locale이나 번역 문장을 알지 않고
 timestamp, number, failure kind 같은 의미 값만 반환한다.
 `src/presentation/i18n`이 typed message catalog, formatter, fallback,
 `<html lang/dir>`과 pseudo/RTL smoke를 소유한다. backend raw `message`는
 application failure registry를 우회해 렌더링할 수 없으며 `check:i18n` negative
 fixture가 이 경계를 집행한다. 번역 vendor를 나중에 선택해도 이 facade 뒤의
 adapter만 교체한다.
 이 문서의 목표 구조는 기존 기반을 폐기하는 것이 아니라 이러한
 불일치를 제거하는 것이다.
@@ -447,6 +447,13 @@ controller가 소유하지 않는 것:
 | Page Template | 반복 layout/state | 접근성과 반응형 구조 재사용 | data fetching을 template에 포함 |
 | Registry + Runtime Map | route/operation/event | 선언과 실행 완전성 | 모든 설정을 하나의 거대 전역 파일에 집중 |
 RP-08 이후 route contract의 `title`/`navigation` 필드는 fallback metadata이며
 실제 document title, navigation, loading/error/access surface는
 `route.<ROUTE_ID>.title|navigation` typed catalog key를 해석한다. route params,
 search, backend message를 translation key로 조립하지 않는다. locale 변경은
 현재 route를 재요청하거나 query key를 바꾸지 않고 document title과 화면 copy만
 다시 렌더링한다.
 패턴은 추상화 파일만 만든 것으로 완료되지 않는다. reference usage, negative
 architecture test, 실패 상태 test가 있어야 제공된 패턴으로 본다.
@@ -485,6 +485,32 @@ raw response body, stack, token, URL query, PII를 사용자 copy나 일반 log
 - logging failure가 제품 flow를 실패시키지 않음
 - consent가 필요한 analytics와 essential diagnostics를 분리
 ### 7.4 locale, message와 표시 값
 RP-08부터 locale은 presentation-owned React context다. server/application
 state에 번역된 문자열을 저장하거나 query key에 locale을 넣는 것은 응답 자체가
 locale별 데이터인 경우에만 허용한다. 공통 UI copy 변경 때문에 query cache를
 복제하지 않는다.
 ```text
 API timestamp/number/failure kind
  -> schema + mapper (의미 값 유지)
  -> application result
  -> presentation controller
  -> useLocale().date/number/message
 ```
 - message key는 `MessageKey` union이며 interpolation은 key별 tuple type이다.
 - unknown external key는 `resolveMessage`에 전달해도 raw key가 표시되지 않는다.
 - backend `message`는 diagnostic input일 수 있지만 사용자 copy가 아니다.
 - form validation code는 `ParameterlessMessageKey` allowlist로 mapping한다.
 - date의 기본 timezone은 UTC이고 제품 timezone은 presentation 호출자가
  명시한다.
 - pseudo/RTL locale state는 local interaction state이며 persistence와 server
  synchronization을 기본 제공하지 않는다.
 - key rename은 typed canonical key를 먼저 이동하고 runtime alias에 migration
  기간을 둔다.
 ## 8. 폼 표준
 VD-04에 따라 현재 기본 엔진은 React native form event와 controlled value이며
@@ -584,4 +610,5 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다.
 - 상태 종류별 소유권이 테스트와 문서에서 확인된다.
 - token은 UI와 일반 storage/store에 노출되지 않는다.
 - failure와 validation의 각 계층이 typed mapper로 분리된다.
 - common UI copy, locale formatter와 direction이 typed i18n facade를 통과한다.
 - query/mutation/form recipe만으로 새 기능을 만들 수 있다.
@@ -534,8 +534,9 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다.
 ## 9. 국제화 계약
-디자인 시스템 primitive는 한국어 문구를 내부 기본값으로 숨기지 않는다.
+RP-08에서 디자인 시스템 primitive의 닫기, alert, toast, 글자 수 같은 기본
-접근성 label이나 오류 문구가 필요하면 명시적인 prop 또는 message key를 받는다.
+문구는 `useLocale()` typed catalog로 이동했다. 제품 의미를 가진 label은 여전히
 명시적인 prop으로 받으며 primitive가 feature message key를 소유하지 않는다.
 필수 국제화 기반:
@@ -551,6 +552,17 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다.
 - pseudo-locale
 - RTL story와 E2E smoke
 현재 구현 위치와 실패 정책:
 - `presentation/i18n/catalog.ts`: 137개 canonical common key와 locale parity
 - `message-contract.ts`: key별 interpolation, fallback과 compatibility alias
 - `formatters.ts`: UTC-default date, number, relative time, list, plural/select
 - `locale-provider.tsx`: document `lang/dir`과 React consumer API
 - missing key/parameter와 formatter 예외: 빈 문자열이나 raw key 대신 안전한
  fallback
 - `en-XA`: 긴 문자열/320px reflow, `ar-EG`: logical layout/RTL keyboard smoke
 - backend raw message와 translated HTML: 정적 negative gate에서 거절
 금지 패턴:
 - 번역 문장 중간에 JSX 문자열을 연결한다.
@@ -559,7 +571,7 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다.
 - route title, navigation label, toast message를 JSX literal로 분산한다.
 - 번역 누락 시 빈 문자열을 렌더링한다.
-Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어야 한다.
+RP-10의 Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어야 한다.
 - `ko-KR`, light
 - `en-US`, light
@@ -569,6 +569,23 @@ RP-07의 실행 경로는 `check:design-system`,
 baseline은 VD-08/RP-10에서 추가하며 현재 runtime gallery를 isolated workshop
 완료 증거로 사용하지 않는다.
 RP-08의 국제화 실행 경로는 `check:i18n`, `check:i18n:fixture`,
 `check:types:fixture:i18n-key`, `check:types:fixture:i18n-params`,
 `tests/unit/i18n-contract.test.ts`, `tests/component/locale-platform.test.tsx`와
 `tests/e2e/i18n.spec.js`다.
 - unit: locale catalog/placeholder parity, safe fallback/alias, pseudo expansion,
  direction과 UTC date/number/relative/list/plural/select
 - component: document `lang/dir`, RTL tab arrow semantics, direction-aware
  pagination과 modal Drawer
 - E2E: 320px pseudo reflow와 compact RTL shell/Drawer/focus restore
 - negative: common UI locale literal, backend message JSX render, raw translated
  HTML, unknown key와 잘못된 interpolation parameter
 `ar-EG` catalog가 영어 smoke copy를 재사용하는 것은 RTL behavior 검증용이며
 번역 품질 PASS가 아니다. 실제 locale catalog에는 언어 담당 승인 evidence가
 추가되어야 한다.
 ### 10.1 Component behavior
 - native role/name/value
@@ -76,6 +76,7 @@ export default [
      "artifacts/**",
      "tests/fixtures/typecheck/**",
      "tests/fixtures/architecture/forbidden/**",
      "tests/fixtures/i18n/forbidden/**",
      "tests/fixtures/security/forbidden/**",
    ],
  },
@@ -17,6 +17,8 @@
    "check:architecture": "node scripts/check-architecture.mjs",
    "check:design-system": "node scripts/check-design-system.mjs",
    "check:design-system:fixture": "node scripts/check-design-system.mjs --fixture",
    "check:i18n": "node scripts/check-i18n.mjs",
    "check:i18n:fixture": "node scripts/check-i18n.mjs --fixture",
    "check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test",
    "check:types:app": "tsc --project tsconfig.app.json",
    "check:types:node": "tsc --project tsconfig.node.json",
@@ -30,6 +32,8 @@
    "check:types:fixture:route-runtime": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-route-runtime.ts",
    "check:types:fixture:page-action": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler --jsx react-jsx tests/fixtures/typecheck/invalid-page-action.tsx",
    "check:types:fixture:icon-button": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler --jsx react-jsx tests/fixtures/typecheck/invalid-icon-button.tsx",
    "check:types:fixture:i18n-key": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-message-key.ts",
    "check:types:fixture:i18n-params": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-message-params.ts",
    "test:runtime-schema": "vitest run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
    "test:unit": "vitest run tests/unit --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/unit.xml",
    "test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml",
@@ -0,0 +1,108 @@
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 // @ts-expect-error Node 24 executes erasable TypeScript for this build-time gate.
 import { EN_MESSAGES, KO_MESSAGES, MESSAGE_CATALOGS } from "../src/presentation/i18n/catalog.ts";
 const fixtureMode = process.argv.includes("--fixture");
 const failures = [];
 const sourceExtensions = /\.(?:js|jsx|mjs|ts|tsx|mts)$/;
 const koreanLiteral = /[가-힣]/;
 const rawFailureRender =
  /(?<!\$)\{\s*(?:failure|error|response|backend)(?:\?\.|\.)[\w?.]*message\s*\}/;
 /** @param {string} directory @returns {Promise<string[]>} */
 async function listSourceFiles(directory) {
  const result = [];
  for (const entry of await readdir(directory, { withFileTypes: true })) {
    const target = path.join(directory, entry.name);
    if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
    else if (sourceExtensions.test(entry.name)) result.push(target);
  }
  return result;
 }
 /** @param {string} template */
 function placeholders(template) {
  return [...template.matchAll(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g)]
    .map((match) => match[1])
    .sort();
 }
 if (!fixtureMode) {
  const canonicalKeys = Object.keys(KO_MESSAGES).sort();
  for (const [locale, catalog] of Object.entries(MESSAGE_CATALOGS)) {
    const readableCatalog =
      /** @type {Readonly<Record<string, string>>} */ (catalog);
    const canonicalCatalog =
      /** @type {Readonly<Record<string, string>>} */ (KO_MESSAGES);
    const keys = Object.keys(catalog).sort();
    if (JSON.stringify(keys) !== JSON.stringify(canonicalKeys)) {
      failures.push(`${locale} catalog keys do not match ko-KR`);
    }
    for (const key of canonicalKeys) {
      if (
        JSON.stringify(placeholders(readableCatalog[key] ?? "")) !==
        JSON.stringify(placeholders(canonicalCatalog[key] ?? ""))
      ) {
        failures.push(`${locale}:${key} interpolation parameters do not match`);
      }
    }
  }
  if (Object.keys(EN_MESSAGES).length !== canonicalKeys.length) {
    failures.push("en-US catalog key count does not match ko-KR");
  }
 }
 const commonDirectories = [
  "src/presentation/boundaries",
  "src/presentation/components",
  "src/presentation/design-system",
  "src/presentation/forms",
  "src/presentation/layouts",
  "src/presentation/routes",
  "src/presentation/templates",
 ];
 const sources = fixtureMode
  ? await listSourceFiles("tests/fixtures/i18n/forbidden")
  : (
      await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
    ).flat();
 for (const file of sources) {
  const source = await readFile(file, "utf8");
  if (koreanLiteral.test(source)) {
    failures.push(`hardcoded common user-facing locale literal in ${file}`);
  }
  if (rawFailureRender.test(source)) {
    failures.push(`raw backend/error message rendered in ${file}`);
  }
  if (source.includes("dangerouslySetInnerHTML")) {
    failures.push(`untrusted HTML interpolation boundary in ${file}`);
  }
 }
 const report = {
  schemaVersion: 1,
  mode: fixtureMode ? "negative-fixture" : "source",
  localeCount: Object.keys(MESSAGE_CATALOGS).length + 1,
  messageKeyCount: Object.keys(KO_MESSAGES).length,
  checkedFiles: sources.length,
  failures,
  passed: failures.length === 0,
 };
 await mkdir("artifacts/quality", { recursive: true });
 await writeFile(
  fixtureMode
    ? "artifacts/quality/i18n-fixture.json"
    : "artifacts/quality/i18n.json",
  `${JSON.stringify(report, null, 2)}\n`,
 );
 if (failures.length > 0) {
  process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
  process.exit(1);
 }
 process.stdout.write(
  `I18n contract: ${report.messageKeyCount} keys across ${report.localeCount} locales PASS\n`,
 );
@@ -89,6 +89,12 @@ export function createInstalledFeatureInputs(_context: FeatureContext) {
 }
 `;
 const emptyMessages = `export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({
  "ko-KR": Object.freeze({}),
  "en-US": Object.freeze({}),
 });
 `;
 /** @param {string} directory @returns {Promise<string[]>} */
 async function filesBelow(directory) {
  const entries = await readdir(directory, { withFileTypes: true });
@@ -135,6 +141,10 @@ await writeFile(
  path.join(fixtureRoot, "src/features/installed-feature-adapters.ts"),
  emptyAdapters,
 );
 await writeFile(
  path.join(fixtureRoot, "src/features/installed-feature-messages.js"),
  emptyMessages,
 );
 /** @type {string[]} */
 const residue = [];
@@ -0,0 +1,10 @@
 import { REFERENCE_MESSAGE_CATALOGS } from "./reference-feature/contracts/reference-message-catalog.js";
 export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({
  "ko-KR": Object.freeze({
    ...REFERENCE_MESSAGE_CATALOGS["ko-KR"],
  }),
  "en-US": Object.freeze({
    ...REFERENCE_MESSAGE_CATALOGS["en-US"],
  }),
 });
@@ -6,7 +6,7 @@ import {
 export type ReferenceResourceView = Readonly<{
  resourceId: string;
  title: string;
-  createdAtLabel: string | null;
+  createdAt: string | null;
  optimistic?: boolean;
 }>;
@@ -44,14 +44,10 @@ export function mapReferenceOperation(
 export function toReferenceView(
  resource: ReferenceResource,
  formatDate: (value: Date) => string = (value) =>
    new Intl.DateTimeFormat("ko-KR").format(value),
 ): ReferenceResourceView {
  return Object.freeze({
    resourceId: resource.id,
    title: resource.displayName,
-    createdAtLabel: resource.createdAt
+    createdAt: resource.createdAt,
      ? formatDate(new Date(resource.createdAt))
      : null,
  });
 }
@@ -0,0 +1,22 @@
 export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
  "ko-KR": Object.freeze({
    "route.REFERENCE_RESOURCE_LIST.navigation": "Reference feature",
    "route.REFERENCE_RESOURCE_LIST.title": "Reference resources",
    "route.REFERENCE_RESOURCE_DETAIL.navigation": "Reference detail",
    "route.REFERENCE_RESOURCE_DETAIL.title": "Reference resource detail",
    "route.REFERENCE_RESOURCE_FORM.navigation": "Reference form",
    "route.REFERENCE_RESOURCE_FORM.title": "Create reference resource",
    "route.REFERENCE_RESOURCE_STATUS.navigation": "Reference status",
    "route.REFERENCE_RESOURCE_STATUS.title": "Reference resource status",
  }),
  "en-US": Object.freeze({
    "route.REFERENCE_RESOURCE_LIST.navigation": "Reference feature",
    "route.REFERENCE_RESOURCE_LIST.title": "Reference resources",
    "route.REFERENCE_RESOURCE_DETAIL.navigation": "Reference detail",
    "route.REFERENCE_RESOURCE_DETAIL.title": "Reference resource detail",
    "route.REFERENCE_RESOURCE_FORM.navigation": "Reference form",
    "route.REFERENCE_RESOURCE_FORM.title": "Create reference resource",
    "route.REFERENCE_RESOURCE_STATUS.navigation": "Reference status",
    "route.REFERENCE_RESOURCE_STATUS.title": "Reference resource status",
  }),
 });
@@ -5,9 +5,11 @@ import {
  DetailPage,
 } from "../../../presentation/design-system/index.js";
 import { useRouteInput } from "../../../presentation/routes/app-router.js";
 import { useLocale } from "../../../presentation/i18n/index.js";
 import { useReferenceDetail } from "./use-reference-feature.js";
 export default function ReferenceResourceDetailPage() {
  const { date, message } = useLocale();
  const route = useRouteInput();
  const resourceId = String(route.params.resourceId);
  const { query } = useReferenceDetail(resourceId);
@@ -30,7 +32,11 @@ export default function ReferenceResourceDetailPage() {
            <dt>Resource ID</dt>
            <dd>{resource.resourceId}</dd>
            <dt>Created</dt>
-            <dd>{resource.createdAtLabel ?? "표시 정보 없음"}</dd>
+            <dd>
              {resource.createdAt
                ? date(new Date(resource.createdAt))
                : message("common.noDisplayValue")}
            </dd>
          </dl>
        ) : (
          <p>요약 정보를 준비하고 있습니다.</p>
@@ -70,7 +70,7 @@ export function useReferenceFeature() {
          {
            resourceId: `optimistic:${command.name}`,
            title: command.name,
-            createdAtLabel: null,
+            createdAt: null,
            optimistic: true,
          },
        ];
@@ -1,3 +1,5 @@
 import { formatMessage } from "../i18n/index.js";
 /**
 * @param {{
 *   kind?: string,
@@ -18,32 +20,36 @@ export function BootErrorShell({
 }) {
  return (
    <main role="alert">
-      <h1>애플리케이션을 시작할 수 없습니다.</h1>
+      <h1>{formatMessage("ko-KR", "boot.failure.title")}</h1>
      <dl>
-        <dt>오류</dt>
+        <dt>{formatMessage("ko-KR", "boot.field.error")}</dt>
        <dd>{kind}</dd>
-        <dt>코드</dt>
+        <dt>{formatMessage("ko-KR", "boot.field.code")}</dt>
        <dd>{code}</dd>
        {buildId && (
          <>
-            <dt>빌드</dt>
+            <dt>{formatMessage("ko-KR", "boot.field.build")}</dt>
            <dd>{buildId}</dd>
          </>
        )}
        {configSchemaVersion && (
          <>
-            <dt>설정 스키마</dt>
+            <dt>{formatMessage("ko-KR", "boot.field.configSchema")}</dt>
            <dd>{configSchemaVersion}</dd>
          </>
        )}
        {releaseId && (
          <>
-            <dt>릴리스</dt>
+            <dt>{formatMessage("ko-KR", "boot.field.release")}</dt>
            <dd>{releaseId}</dd>
          </>
        )}
      </dl>
-      <p>지원 참조: {supportReference}</p>
+      <p>
        {formatMessage("ko-KR", "boot.supportReference", {
          reference: supportReference,
        })}
      </p>
    </main>
  );
 }
@@ -3,6 +3,7 @@ import {
  type ErrorInfo,
  type ReactNode,
 } from "react";
 import { useLocale } from "../i18n/index.js";
 type RecoveryResult =
  | Readonly<{ action: "reload-once"; releasePair: string }>
@@ -71,27 +72,44 @@ export class ChunkRecoveryBoundary extends Component<Props, State> {
    const { error, recovery, reason } = this.state;
    if (error && !isChunkLoadFailure(error)) throw error;
    if (error && recovery === "checking") {
-      return (
+      return <ChunkRecoverySurface recovery="checking" />;
        <section className="ui-page" aria-live="polite" aria-busy="true">
          새 릴리스 정보를 확인하고 있습니다.
        </section>
      );
    }
    if (error && recovery === "reload-requested") {
-      return (
+      return <ChunkRecoverySurface recovery="reload-requested" />;
        <section className="ui-page" aria-live="polite">
          새 버전으로 한 번만 전환합니다.
        </section>
      );
    }
    if (error && recovery === "support") {
-      return (
+      return <ChunkRecoverySurface recovery="support" reason={reason} />;
        <section className="ui-page" role="alert" data-recovery-reason={reason}>
          <h1>화면 자산을 복구하지 못했습니다.</h1>
          <p>문제가 계속되면 배포 상태와 지원 참조 정보를 확인해 주세요.</p>
        </section>
      );
    }
    return this.props.children;
  }
 }
 function ChunkRecoverySurface({
  recovery,
  reason,
 }: Readonly<{
  recovery: Exclude<State["recovery"], "idle">;
  reason?: string;
 }>) {
  const { message } = useLocale();
  if (recovery === "checking") {
    return (
      <section className="ui-page" aria-live="polite" aria-busy="true">
        {message("chunk.checking")}
      </section>
    );
  }
  if (recovery === "reload-requested") {
    return (
      <section className="ui-page" aria-live="polite">
        {message("chunk.reloadOnce")}
      </section>
    );
  }
  return (
    <section className="ui-page" role="alert" data-recovery-reason={reason}>
      <h1>{message("chunk.failure.title")}</h1>
      <p>{message("chunk.failure.description")}</p>
    </section>
  );
 }
@@ -1,4 +1,5 @@
 import { Component } from "react";
 import { formatMessage } from "../i18n/index.js";
 /**
 * @typedef {{
@@ -57,9 +58,9 @@ export class RenderErrorBoundary extends Component {
      return (
        this.props.fallback ?? (
          <section role="alert">
-            <p>error.render_failure</p>
+            <p>{formatMessage("ko-KR", "error.render_failure")}</p>
            <button type="button" onClick={this.reset}>
-              retry
+              {formatMessage("ko-KR", "action.retry")}
            </button>
          </section>
        )
@@ -2,19 +2,22 @@ import { useId } from "react";
 import { errorMessage } from "./error-copy.js";
 import { Button } from "./ui/button.jsx";
 import { useLocale } from "../i18n/index.js";
 /** @param {{ label?: string }} props */
-export function LoadingSurface({ label = "불러오는 중" }) {
+export function LoadingSurface({ label }) {
  const { message } = useLocale();
  const accessibleLabel = label ?? message("async.loading");
  return (
    <section
      className="state-surface state-surface--loading"
      aria-busy="true"
-      aria-label={label}
+      aria-label={accessibleLabel}
      aria-live="polite"
      aria-atomic="true"
    >
      <div className="ui-skeleton" aria-hidden="true" />
-      <span className="visually-hidden">{label}</span>
+      <span className="visually-hidden">{accessibleLabel}</span>
    </section>
  );
 }
@@ -27,13 +30,14 @@ export function LoadingSurface({ label = "불러오는 중" }) {
 * }} props
 */
 export function EmptySurface({
-  title = "표시할 항목이 없습니다.",
+  title,
  description,
  action,
 }) {
  const { message } = useLocale();
  return (
    <section className="ui-empty state-surface" aria-live="polite">
-      <h2>{title}</h2>
+      <h2>{title ?? message("async.empty")}</h2>
      {description ? <p>{description}</p> : null}
      {action}
    </section>
@@ -49,13 +53,14 @@ export function EmptySurface({
 * }} props
 */
 export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
  const { locale, message } = useLocale();
  const messageId = useId();
  const actionLabels = Object.freeze({
-    retry: "다시 시도",
+    retry: message("action.retry"),
-    reauth: "로그인",
+    reauth: message("action.reauth"),
-    navigate: "안전한 화면으로 이동",
+    navigate: message("action.navigateSafe"),
-    "reload-once": "한 번 새로고침",
+    "reload-once": message("action.reloadOnce"),
-    "contact-support": "지원 정보 확인",
+    "contact-support": message("action.contactSupport"),
  });
  return (
    <section
@@ -64,7 +69,7 @@ export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
      aria-labelledby={messageId}
      data-message-key={userMessageKey}
    >
-      <h2 id={messageId}>{errorMessage(userMessageKey)}</h2>
+      <h2 id={messageId}>{errorMessage(userMessageKey, locale)}</h2>
      {action !== "none" && onAction && (
        <Button onClick={onAction}>{actionLabels[action]}</Button>
      )}
@@ -88,6 +93,7 @@ export function AsyncSurface({
  onRetry,
  onResolveConflict,
 }) {
  const { message } = useLocale();
  if (state.base === "initial-loading") return <LoadingSurface />;
  if (state.base === "empty") return <EmptySurface />;
  if (state.base === "terminal-error" && state.failure) {
@@ -104,12 +110,24 @@ export function AsyncSurface({
    <section aria-busy={state.overlay.refreshing || state.overlay.mutationPending}>
      {state.indicator ? (
        <div role="status" aria-live="polite">
-          <span>{state.indicator}</span>
+          <span>
            {message(
              state.indicator === "stale-degraded"
                ? "async.staleDegraded"
                : state.indicator === "mutation-conflict"
                  ? "async.mutationConflict"
                  : state.indicator === "mutation-pending"
                    ? "async.mutationPending"
                    : "async.refreshing",
            )}
          </span>
          {state.indicator === "stale-degraded" && onRetry ? (
-            <Button onClick={onRetry}>다시 시도</Button>
+            <Button onClick={onRetry}>{message("action.retry")}</Button>
          ) : null}
          {state.indicator === "mutation-conflict" && onResolveConflict ? (
-            <Button onClick={onResolveConflict}>충돌 해결</Button>
+            <Button onClick={onResolveConflict}>
              {message("action.resolveConflict")}
            </Button>
          ) : null}
        </div>
      ) : null}
@@ -1,26 +1,6 @@
-const ERROR_MESSAGES = Object.freeze({
+import { resolveMessage } from "../i18n/index.js";
  "error.network_unreachable": "네트워크에 연결할 수 없습니다.",
  "error.request_timeout": "요청 시간이 초과되었습니다.",
  "error.auth_required": "계속하려면 로그인이 필요합니다.",
  "error.auth_integration_failure": "로그인 연동을 사용할 수 없습니다.",
  "error.forbidden": "이 작업을 수행할 권한이 없습니다.",
  "error.not_found": "요청한 항목을 찾을 수 없습니다.",
  "error.rate_limited": "요청이 많습니다. 잠시 후 다시 시도해 주세요.",
  "error.server_failure": "요청을 완료하지 못했습니다.",
  "error.chunk_load_failure": "새 화면 파일을 불러오지 못했습니다.",
  "error.build_mismatch": "현재 화면과 활성 빌드가 일치하지 않습니다.",
  "error.config_mismatch": "런타임 설정 버전이 현재 화면과 일치하지 않습니다.",
  "error.api_contract_mismatch": "API 계약 버전이 현재 화면과 일치하지 않습니다.",
  "error.release_mismatch": "현재 화면과 활성 릴리스가 일치하지 않습니다.",
  "error.asset_mismatch": "화면 자산 구성이 현재 릴리스와 일치하지 않습니다.",
  "error.render_failure": "화면을 표시하지 못했습니다.",
  "error.unknown_failure": "예상하지 못한 문제가 발생했습니다.",
 });
-/** @param {string} messageKey */
+/** @param {string} messageKey @param {string} [locale] */
-export function errorMessage(messageKey) {
+export function errorMessage(messageKey, locale = "ko-KR") {
-  const messages = /** @type {Readonly<Record<string, string>>} */ (
+  return resolveMessage(locale, messageKey);
    ERROR_MESSAGES
  );
  return messages[messageKey] ?? "요청을 완료하지 못했습니다.";
 }
@@ -1,4 +1,5 @@
 import { Button } from "./ui/button.jsx";
 import { useLocale } from "../i18n/index.js";
 /**
 * @param {{
@@ -30,12 +31,13 @@ function StateSurface({
 /** @param {{ onSignIn?: () => void }} props */
 export function AuthRequiredSurface({ onSignIn }) {
  const { message } = useLocale();
  return (
    <StateSurface
-      eyebrow="401 · 인증 필요"
+      eyebrow={message("access.auth.eyebrow")}
-      title="로그인이 필요합니다."
+      title={message("access.auth.title")}
-      description="세션을 시작한 뒤 이전 작업을 안전하게 계속할 수 있습니다."
+      description={message("access.auth.description")}
-      actionLabel="로그인 시작"
+      actionLabel={message("action.signIn")}
      onAction={onSignIn}
    />
  );
@@ -43,12 +45,13 @@ export function AuthRequiredSurface({ onSignIn }) {
 /** @param {{ onNavigate?: () => void }} props */
 export function ForbiddenSurface({ onNavigate }) {
  const { message } = useLocale();
  return (
    <StateSurface
-      eyebrow="403 · 권한 없음"
+      eyebrow={message("access.forbidden.eyebrow")}
-      title="접근할 수 없습니다."
+      title={message("access.forbidden.title")}
-      description="권한을 확인하거나 접근 가능한 화면으로 이동하세요."
+      description={message("access.forbidden.description")}
-      actionLabel="안전한 화면으로 이동"
+      actionLabel={message("action.navigateSafe")}
      onAction={onNavigate}
      tone="warning"
    />
@@ -57,12 +60,13 @@ export function ForbiddenSurface({ onNavigate }) {
 /** @param {{ onNavigate?: () => void }} props */
 export function NotFoundSurface({ onNavigate }) {
  const { message } = useLocale();
  return (
    <StateSurface
-      eyebrow="404 · 찾을 수 없음"
+      eyebrow={message("access.notFound.eyebrow")}
-      title="요청한 화면이 없습니다."
+      title={message("access.notFound.title")}
-      description="주소를 확인하거나 시작 화면으로 돌아가세요."
+      description={message("access.notFound.description")}
-      actionLabel="시작 화면으로 이동"
+      actionLabel={message("action.goHome")}
      onAction={onNavigate}
    />
  );
@@ -8,6 +8,7 @@ import {
 import { createPortal } from "react-dom";
 import { CloseIcon } from "../icons/semantic-icons.js";
 import { useLocale } from "../../i18n/index.js";
 export type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
 export type ButtonSize = "default" | "compact";
@@ -277,6 +278,7 @@ export function Alert({
  dismissLabel,
  onDismiss,
 }: AlertProps) {
  const { message } = useLocale();
  return (
    <section
      className={`ui-alert ui-alert--${variant}`}
@@ -288,7 +290,9 @@ export function Alert({
      </div>
      {onDismiss ? (
        <IconButton
-          accessibleName={dismissLabel ?? `${title} 알림 닫기`}
+          accessibleName={
            dismissLabel ?? message("action.alertCloseNamed", { title })
          }
          className="ui-alert__dismiss"
          onClick={onDismiss}
          variant="ghost"
@@ -334,6 +338,7 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
    },
    forwardedRef,
  ) {
    const { message } = useLocale();
    const dialogRef = useRef<HTMLDialogElement | null>(null);
    const previousFocusRef = useRef<HTMLElement | null>(null);
    const titleId = useId();
@@ -364,8 +369,11 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
        if (typeof dialog.close === "function") dialog.close();
        else dialog.removeAttribute("open");
      }
-      previousFocusRef.current?.focus();
+      const previousFocus = previousFocusRef.current;
      previousFocusRef.current = null;
      queueMicrotask(() => {
        if (previousFocus?.isConnected) previousFocus.focus();
      });
    }, [open]);
    return (
@@ -395,7 +403,9 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
              {description ? <p id={descriptionId}>{description}</p> : null}
            </div>
            <IconButton
-              accessibleName={closeLabel ?? `${title} 닫기`}
+              accessibleName={
                closeLabel ?? message("action.closeNamed", { title })
              }
              className="ui-dialog__close"
              onClick={onClose}
              variant="ghost"
@@ -9,6 +9,7 @@ import {
 import { CloseIcon, SearchIcon } from "../icons/semantic-icons.js";
 import { Field, IconButton } from "./core.js";
 import type { TextFieldProps } from "./core.js";
 import { useLocale } from "../../i18n/index.js";
 type FieldCopy = Readonly<{
  id?: string;
@@ -41,6 +42,7 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
    },
    ref,
  ) {
    const { message } = useLocale();
    const [uncontrolledValue, setUncontrolledValue] = useState(
      String(defaultValue ?? ""),
    );
@@ -80,7 +82,7 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
              <output className="ui-field__counter">
                {maxLengthMessage
                  ? maxLengthMessage(remaining)
-                  : `${remaining}자 남음`}
+                  : message("form.remaining", { count: remaining })}
              </output>
            ) : null}
          </>
@@ -1,5 +1,6 @@
 import { useId, useRef, useState } from "react";
 import { useLocale } from "../../i18n/index.js";
 import { NextIcon, PreviousIcon } from "../icons/semantic-icons.js";
 import { IconButton, LinkButton } from "./core.js";
@@ -62,6 +63,7 @@ export function Tabs({
  const selected = value ?? internalValue;
  const tabRefs = useRef<Array<HTMLButtonElement | null>>([]);
  const baseId = useId();
  const { direction } = useLocale();
  function select(id: string) {
    if (value === undefined) setInternalValue(id);
@@ -98,10 +100,10 @@ export function Tabs({
            onKeyDown={(event) => {
              if (event.key === "ArrowRight") {
                event.preventDefault();
-                move(index, 1);
+                move(index, direction === "rtl" ? -1 : 1);
              } else if (event.key === "ArrowLeft") {
                event.preventDefault();
-                move(index, -1);
+                move(index, direction === "rtl" ? 1 : -1);
              } else if (
                activation === "manual" &&
                (event.key === "Enter" || event.key === " ")
@@ -156,6 +158,10 @@ export function Pagination({
  onChange(page: number): void;
 }>) {
  const pages = Array.from({ length: pageCount }, (_, index) => index + 1);
  const { direction } = useLocale();
  const PreviousDirectionalIcon =
    direction === "rtl" ? NextIcon : PreviousIcon;
  const NextDirectionalIcon = direction === "rtl" ? PreviousIcon : NextIcon;
  return (
    <nav aria-label={label} className="ui-pagination">
      <IconButton
@@ -164,7 +170,7 @@ export function Pagination({
        onClick={() => onChange(page - 1)}
        variant="secondary"
      >
-        <PreviousIcon />
+        <PreviousDirectionalIcon />
      </IconButton>
      {pages.map((candidate) => (
        <LinkButton
@@ -186,7 +192,7 @@ export function Pagination({
        onClick={() => onChange(page + 1)}
        variant="secondary"
      >
-        <NextIcon />
+        <NextDirectionalIcon />
      </IconButton>
    </nav>
  );
@@ -11,6 +11,7 @@ import {
 import { CloseIcon } from "../icons/semantic-icons.js";
 import { Button, Dialog, IconButton } from "./core.js";
 import { useLocale } from "../../i18n/index.js";
 export type DrawerProps = Readonly<{
  open: boolean;
@@ -343,9 +344,10 @@ function ToastRegion({
  toasts: readonly ToastEntry[];
  dismiss(id: string): void;
 }>) {
  const { message } = useLocale();
  return (
    <section
-      aria-label="Notifications"
+      aria-label={message("toast.region")}
      aria-live="polite"
      className="ui-toast-region"
    >
@@ -363,6 +365,7 @@ function ToastItem({
  toast: ToastEntry;
  dismiss(id: string): void;
 }>) {
  const { message } = useLocale();
  const [paused, setPaused] = useState(false);
  useEffect(() => {
    if (paused) return;
@@ -391,7 +394,7 @@ function ToastItem({
        {toast.description ? <p>{toast.description}</p> : null}
      </div>
      <IconButton
-        accessibleName={`${toast.title} 닫기`}
+        accessibleName={message("action.closeNamed", { title: toast.title })}
        onClick={() => dismiss(toast.id)}
        variant="ghost"
      >
@@ -1,6 +1,7 @@
 import { useId, type FormHTMLAttributes, type ReactNode } from "react";
 import { TextField } from "../components/ui/text-field.jsx";
 import { useLocale } from "../i18n/index.js";
 import type {
  FieldErrors,
  FieldName,
@@ -31,6 +32,7 @@ export function ErrorSummary<Values extends FormValues>(props: Readonly<{
  fieldId(name: FieldName<Values>): string;
  onFocusField?(name: FieldName<Values>): void;
 }>) {
  const { message } = useLocale();
  const {
    fieldErrors,
    formErrors = [],
@@ -50,7 +52,7 @@ export function ErrorSummary<Values extends FormValues>(props: Readonly<{
      role="alert"
      aria-labelledby={headingId}
    >
-      <h2 id={headingId}>입력 내용을 확인해 주세요.</h2>
+      <h2 id={headingId}>{message("form.errorSummary")}</h2>
      {entries.length > 0 ? (
        <ul>
          {entries.map(([name, message]) => (
@@ -1,4 +1,8 @@
 import type { ApiFailure } from "../../contracts/errors.js";
 import {
  formatMessage,
  type ParameterlessMessageKey,
 } from "../i18n/index.js";
 export type FormValues = Readonly<Record<string, unknown>>;
 export type FieldName<Values extends FormValues> = Extract<keyof Values, string>;
@@ -23,24 +27,32 @@ export type MappedValidationFailure<Values extends FormValues> = Readonly<{
 }>;
 const VALIDATION_COPY = Object.freeze({
-  REQUIRED: "필수 입력값입니다.",
+  REQUIRED: "form.validation.required",
-  too_small: "입력값이 너무 짧습니다.",
+  too_small: "form.validation.tooSmall",
-  too_big: "입력값이 너무 깁니다.",
+  too_big: "form.validation.tooBig",
-  invalid_type: "입력 형식을 확인해 주세요.",
+  invalid_type: "form.validation.invalidType",
-  invalid_format: "입력 형식을 확인해 주세요.",
+  invalid_format: "form.validation.invalidFormat",
-  invalid_value: "허용된 값을 선택해 주세요.",
+  invalid_value: "form.validation.invalidValue",
 });
-export function validationMessage(code: string): string {
+type MessageResolver = (key: ParameterlessMessageKey) => string;
-  return (
+
 const defaultMessage: MessageResolver = (key) => formatMessage("ko-KR", key);
 export function validationMessage(
  code: string,
  message: MessageResolver = defaultMessage,
 ): string {
  return message(
    VALIDATION_COPY[code as keyof typeof VALIDATION_COPY] ??
-    "입력값을 확인해 주세요."
+      "form.validation.unknown",
  );
 }
 export function mapValidationFailureToFields<Values extends FormValues>(
  failure: ApiFailure,
  allowedFields: readonly FieldName<Values>[],
  message: MessageResolver = defaultMessage,
 ): MappedValidationFailure<Values> {
  if (failure.kind !== "VALIDATION_REJECTED") {
    return Object.freeze({ fieldErrors: Object.freeze({}), formErrors: [] });
@@ -51,15 +63,15 @@ export function mapValidationFailureToFields<Values extends FormValues>(
  const issues = failure.validationIssues ?? [];
  if (issues.length === 0) {
-    formErrors.push("입력값을 다시 확인해 주세요.");
+    formErrors.push(message("form.validation.retry"));
  }
  for (const issue of issues) {
    const field = issue.path.split(".").at(0) ?? "";
    if (allowed.has(field)) {
      const name = field as FieldName<Values>;
-      fieldErrors[name] ??= validationMessage(issue.code);
+      fieldErrors[name] ??= validationMessage(issue.code, message);
    } else {
-      formErrors.push("서버가 확인하지 못한 입력 항목이 있습니다.");
+      formErrors.push(message("form.validation.unknownField"));
    }
  }
  return Object.freeze({
@@ -8,6 +8,10 @@ import {
  type FormEvent,
 } from "react";
 import type { ZodType, ZodIssue } from "zod";
 import {
  useLocale,
  type ParameterlessMessageKey,
 } from "../i18n/index.js";
 import {
  mapValidationFailureToFields,
@@ -37,6 +41,7 @@ export function useAppForm<
  Command,
  Output,
 >(options: AppFormOptions<Values, Command, Output>) {
  const { message } = useLocale();
  const {
    schema,
    defaultValues,
@@ -142,13 +147,14 @@ export function useAppForm<
        const errors = issuesToFieldErrors<Values>(
          parsed.error.issues,
          allowedServerFields,
          message,
        );
        setFieldErrors(errors);
        setFormErrors(
          parsed.error.issues.some(
            (issue) => !allowedServerFields.includes(issue.path[0] as FieldName<Values>),
          )
-            ? ["입력 구성을 다시 확인해 주세요."]
+            ? [message("form.validation.configuration")]
            : [],
        );
        setTouched(new Set(allowedServerFields));
@@ -178,6 +184,7 @@ export function useAppForm<
          const mapped = mapValidationFailureToFields<Values>(
            outcome.error,
            allowedServerFields,
            message,
          );
          setFieldErrors(mapped.fieldErrors);
          setFormErrors(mapped.formErrors);
@@ -185,11 +192,11 @@ export function useAppForm<
          focusFirstError(mapped.fieldErrors);
        } else if (outcome.error.kind === "CONFLICT") {
          setFormErrors([
-            "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.",
+            message("form.conflict"),
          ]);
          setResult("conflict");
        } else {
-          setFormErrors(["저장하지 못했습니다. 잠시 후 다시 시도해 주세요."]);
+          setFormErrors([message("form.unavailable")]);
          setResult("unavailable");
        }
        return outcome;
@@ -203,6 +210,7 @@ export function useAppForm<
      defaultValues,
      focusFirstError,
      mapToCommand,
      message,
      resetOnSuccess,
      schema,
      submit,
@@ -231,6 +239,7 @@ export function useAppForm<
 function issuesToFieldErrors<Values extends FormValues>(
  issues: readonly ZodIssue[],
  allowedFields: readonly FieldName<Values>[],
  message: (key: ParameterlessMessageKey) => string,
 ): FieldErrors<Values> {
  const allowed = new Set<PropertyKey>(allowedFields);
  const errors: Partial<Record<FieldName<Values>, string>> = {};
@@ -238,7 +247,7 @@ function issuesToFieldErrors<Values extends FormValues>(
    const field = issue.path[0];
    if (!allowed.has(field)) continue;
    const name = field as FieldName<Values>;
-    errors[name] ??= validationMessage(issue.code);
+    errors[name] ??= validationMessage(issue.code, message);
  }
  return Object.freeze(errors);
 }
@@ -3,6 +3,7 @@ import { useBeforeUnload, useBlocker } from "react-router-dom";
 import { Button } from "../components/ui/button.jsx";
 import { Dialog } from "../components/ui/dialog.jsx";
 import { useLocale } from "../i18n/index.js";
 export function useDirtyNavigationGuard(when: boolean) {
  const blocker = useBlocker(when);
@@ -33,19 +34,20 @@ export function useDirtyNavigationGuard(when: boolean) {
 export function DirtyNavigationDialog(props: Readonly<{
  guard: ReturnType<typeof useDirtyNavigationGuard>;
 }>) {
  const { message } = useLocale();
  return (
    <Dialog
      open={props.guard.blocked}
      onClose={props.guard.stay}
-      title="저장하지 않은 변경이 있습니다."
+      title={message("form.unsaved.title")}
-      description="이 화면을 떠나면 입력한 내용이 사라집니다."
+      description={message("form.unsaved.description")}
      actions={
        <>
          <Button variant="secondary" onClick={props.guard.stay}>
-            계속 작성
+            {message("action.continueEditing")}
          </Button>
          <Button variant="danger" onClick={props.guard.leave}>
-            변경 버리고 이동
+            {message("action.discardAndLeave")}
          </Button>
        </>
      }
@@ -0,0 +1,304 @@
 import { INSTALLED_MESSAGE_CATALOGS } from "../../features/installed-feature-messages.js";
 const PLATFORM_KO_MESSAGES = {
  "common.unavailable": "요청한 문구를 표시할 수 없습니다.",
  "common.processing": "처리 중…",
  "common.appName": "Frontend Skeleton",
  "common.noDisplayValue": "표시 정보 없음",
  "action.retry": "다시 시도",
  "action.reauth": "로그인",
  "action.navigateSafe": "안전한 화면으로 이동",
  "action.reloadOnce": "한 번 새로고침",
  "action.contactSupport": "지원 정보 확인",
  "action.resolveConflict": "충돌 해결",
  "action.continueEditing": "계속 작성",
  "action.discardAndLeave": "변경 버리고 이동",
  "action.signIn": "로그인 시작",
  "action.recoverSession": "세션 복구",
  "action.signOut": "로그아웃",
  "action.goHome": "홈으로 이동",
  "action.closeNamed": "{title} 닫기",
  "action.alertCloseNamed": "{title} 알림 닫기",
  "shell.skipToContent": "본문으로 건너뛰기",
  "shell.menu": "메뉴",
  "shell.closeMenu": "메뉴 닫기",
  "shell.sidebar": "사이드바",
  "shell.primaryNavigation": "주요 탐색",
  "shell.theme": "색상 테마",
  "shell.theme.system": "시스템 테마",
  "shell.theme.light": "라이트 테마",
  "shell.theme.dark": "다크 테마",
  "shell.locale": "언어",
  "shell.locale.ko": "한국어",
  "shell.locale.en": "English",
  "shell.locale.pseudo": "Pseudo",
  "shell.locale.rtl": "RTL smoke",
  "shell.session.authenticated": "인증됨",
  "shell.session.unauthenticated": "로그인 전",
  "shell.session.recoveryPending": "복구 대기",
  "shell.session.integrationFailed": "연동 필요",
  "shell.session.actionFailed": "세션 작업을 완료하지 못했습니다.",
  "route.APP_HOME.navigation": "홈",
  "route.APP_HOME.title": "Clean Architecture Frontend",
  "route.EXAMPLES_UI.navigation": "UI 구성요소",
  "route.EXAMPLES_UI.title": "UI 구성요소",
  "route.EXAMPLES_STATES.navigation": "화면 상태",
  "route.EXAMPLES_STATES.title": "화면 상태",
  "route.EXAMPLES_AUTH.navigation": "인증 연동",
  "route.EXAMPLES_AUTH.title": "인증 연동",
  "route.NOT_FOUND.navigation": "찾을 수 없음",
  "route.NOT_FOUND.title": "페이지를 찾을 수 없습니다.",
  "async.loading": "불러오는 중",
  "async.empty": "표시할 항목이 없습니다.",
  "async.refreshing": "최신 정보를 확인하고 있습니다.",
  "async.staleDegraded": "기존 정보를 표시하고 있습니다.",
  "async.mutationPending": "변경 사항을 저장하고 있습니다.",
  "async.mutationConflict": "다른 변경과 충돌했습니다.",
  "access.auth.eyebrow": "401 · 인증 필요",
  "access.auth.title": "로그인이 필요합니다.",
  "access.auth.description":
    "세션을 시작한 뒤 이전 작업을 안전하게 계속할 수 있습니다.",
  "access.forbidden.eyebrow": "403 · 권한 없음",
  "access.forbidden.title": "접근할 수 없습니다.",
  "access.forbidden.description":
    "권한을 확인하거나 접근 가능한 화면으로 이동하세요.",
  "access.notFound.eyebrow": "404 · 찾을 수 없음",
  "access.notFound.title": "요청한 화면이 없습니다.",
  "access.notFound.description":
    "주소를 확인하거나 시작 화면으로 돌아가세요.",
  "route.loading": "화면을 준비하고 있습니다.",
  "route.loadingNamed": "{title} 로딩 중",
  "route.failure.title": "화면을 표시하지 못했습니다.",
  "route.failure.description":
    "잠시 후 다시 시도해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요.",
  "route.invalid.title": "올바르지 않은 주소입니다.",
  "route.invalid.description": "주소의 경로 또는 검색 조건을 확인해 주세요.",
  "route.invalid.action": "안전한 탐색 링크를 사용해 주세요.",
  "route.auth.integration.title": "로그인 연동이 필요합니다.",
  "route.auth.integration.description":
    "외부 인증 소유자가 연결되면 이 보호 라우트를 사용할 수 있습니다.",
  "route.auth.recovering.title": "세션을 복구하고 있습니다.",
  "route.auth.required.title": "세션이 필요합니다.",
  "route.auth.recovering.description":
    "기존 세션 확인을 계속하려면 복구를 실행하세요.",
  "route.auth.required.description":
    "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다.",
  "route.documentTitle": "{title} · {appName}",
  "chunk.checking": "새 릴리스 정보를 확인하고 있습니다.",
  "chunk.reloadOnce": "새 버전으로 한 번만 전환합니다.",
  "chunk.failure.title": "화면 자산을 복구하지 못했습니다.",
  "chunk.failure.description":
    "문제가 계속되면 배포 상태와 지원 참조 정보를 확인해 주세요.",
  "page.notFound.title": "페이지를 찾을 수 없습니다.",
  "page.notFound.description":
    "주소를 확인하거나 준비된 시작 화면으로 돌아가세요.",
  "template.breadcrumb": "현재 위치",
  "template.relatedInformation": "관련 정보",
  "template.searchAndFilter": "검색과 필터",
  "template.pagination": "페이지 탐색",
  "template.summary": "요약 정보",
  "template.dangerActions": "위험 작업",
  "template.supportReference": "지원 참조: {reference}",
  "form.errorSummary": "입력 내용을 확인해 주세요.",
  "form.unsaved.title": "저장하지 않은 변경이 있습니다.",
  "form.unsaved.description": "이 화면을 떠나면 입력한 내용이 사라집니다.",
  "form.validation.required": "필수 입력값입니다.",
  "form.validation.tooSmall": "입력값이 너무 짧습니다.",
  "form.validation.tooBig": "입력값이 너무 깁니다.",
  "form.validation.invalidType": "입력 형식을 확인해 주세요.",
  "form.validation.invalidFormat": "입력 형식을 확인해 주세요.",
  "form.validation.invalidValue": "허용된 값을 선택해 주세요.",
  "form.validation.unknown": "입력값을 확인해 주세요.",
  "form.validation.retry": "입력값을 다시 확인해 주세요.",
  "form.validation.unknownField":
    "서버가 확인하지 못한 입력 항목이 있습니다.",
  "form.validation.configuration": "입력 구성을 다시 확인해 주세요.",
  "form.conflict":
    "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.",
  "form.unavailable": "저장하지 못했습니다. 잠시 후 다시 시도해 주세요.",
  "form.remaining": "{count}자 남음",
  "toast.region": "알림",
  "error.network_unreachable": "네트워크에 연결할 수 없습니다.",
  "error.request_timeout": "요청 시간이 초과되었습니다.",
  "error.auth_required": "계속하려면 로그인이 필요합니다.",
  "error.auth_integration_failure": "로그인 연동을 사용할 수 없습니다.",
  "error.forbidden": "이 작업을 수행할 권한이 없습니다.",
  "error.not_found": "요청한 항목을 찾을 수 없습니다.",
  "error.rate_limited": "요청이 많습니다. 잠시 후 다시 시도해 주세요.",
  "error.server_failure": "요청을 완료하지 못했습니다.",
  "error.chunk_load_failure": "새 화면 파일을 불러오지 못했습니다.",
  "error.build_mismatch": "현재 화면과 활성 빌드가 일치하지 않습니다.",
  "error.config_mismatch": "런타임 설정 버전이 현재 화면과 일치하지 않습니다.",
  "error.api_contract_mismatch": "API 계약 버전이 현재 화면과 일치하지 않습니다.",
  "error.release_mismatch": "현재 화면과 활성 릴리스가 일치하지 않습니다.",
  "error.asset_mismatch": "화면 자산 구성이 현재 릴리스와 일치하지 않습니다.",
  "error.render_failure": "화면을 표시하지 못했습니다.",
  "error.unknown_failure": "예상하지 못한 문제가 발생했습니다.",
  "boot.failure.title": "애플리케이션을 시작할 수 없습니다.",
  "boot.field.error": "오류",
  "boot.field.code": "코드",
  "boot.field.build": "빌드",
  "boot.field.configSchema": "설정 스키마",
  "boot.field.release": "릴리스",
  "boot.supportReference": "지원 참조: {reference}",
 } as const;
 export const KO_MESSAGES = {
  ...PLATFORM_KO_MESSAGES,
  ...INSTALLED_MESSAGE_CATALOGS["ko-KR"],
 } as const;
 export type MessageKey = keyof typeof KO_MESSAGES;
 const PLATFORM_EN_MESSAGES = {
  "common.unavailable": "This message is unavailable.",
  "common.processing": "Processing…",
  "common.appName": "Frontend Skeleton",
  "common.noDisplayValue": "No display value",
  "action.retry": "Try again",
  "action.reauth": "Sign in",
  "action.navigateSafe": "Go to an available page",
  "action.reloadOnce": "Reload once",
  "action.contactSupport": "View support information",
  "action.resolveConflict": "Resolve conflict",
  "action.continueEditing": "Continue editing",
  "action.discardAndLeave": "Discard and leave",
  "action.signIn": "Start sign-in",
  "action.recoverSession": "Recover session",
  "action.signOut": "Sign out",
  "action.goHome": "Go home",
  "action.closeNamed": "Close {title}",
  "action.alertCloseNamed": "Dismiss {title} alert",
  "shell.skipToContent": "Skip to content",
  "shell.menu": "Menu",
  "shell.closeMenu": "Close menu",
  "shell.sidebar": "Sidebar",
  "shell.primaryNavigation": "Primary navigation",
  "shell.theme": "Color theme",
  "shell.theme.system": "System theme",
  "shell.theme.light": "Light theme",
  "shell.theme.dark": "Dark theme",
  "shell.locale": "Language",
  "shell.locale.ko": "한국어",
  "shell.locale.en": "English",
  "shell.locale.pseudo": "Pseudo",
  "shell.locale.rtl": "RTL smoke",
  "shell.session.authenticated": "Authenticated",
  "shell.session.unauthenticated": "Signed out",
  "shell.session.recoveryPending": "Recovery pending",
  "shell.session.integrationFailed": "Integration required",
  "shell.session.actionFailed": "The session action could not be completed.",
  "route.APP_HOME.navigation": "Home",
  "route.APP_HOME.title": "Clean Architecture Frontend",
  "route.EXAMPLES_UI.navigation": "UI components",
  "route.EXAMPLES_UI.title": "UI components",
  "route.EXAMPLES_STATES.navigation": "Screen states",
  "route.EXAMPLES_STATES.title": "Screen states",
  "route.EXAMPLES_AUTH.navigation": "Authentication",
  "route.EXAMPLES_AUTH.title": "Authentication",
  "route.NOT_FOUND.navigation": "Not found",
  "route.NOT_FOUND.title": "Page not found",
  "async.loading": "Loading",
  "async.empty": "There are no items to display.",
  "async.refreshing": "Checking for the latest information.",
  "async.staleDegraded": "Showing previously loaded information.",
  "async.mutationPending": "Saving changes.",
  "async.mutationConflict": "The change conflicts with another update.",
  "access.auth.eyebrow": "401 · Authentication required",
  "access.auth.title": "Sign-in is required.",
  "access.auth.description":
    "Start a session to safely continue the previous task.",
  "access.forbidden.eyebrow": "403 · Access denied",
  "access.forbidden.title": "You cannot access this page.",
  "access.forbidden.description":
    "Check your permissions or go to an available page.",
  "access.notFound.eyebrow": "404 · Not found",
  "access.notFound.title": "The requested page does not exist.",
  "access.notFound.description": "Check the address or return to the start page.",
  "route.loading": "Preparing the page.",
  "route.loadingNamed": "Loading {title}",
  "route.failure.title": "The page could not be displayed.",
  "route.failure.description":
    "Try again shortly. If the problem continues, check the support reference.",
  "route.invalid.title": "This address is invalid.",
  "route.invalid.description": "Check the path and search parameters.",
  "route.invalid.action": "Use a safe navigation link.",
  "route.auth.integration.title": "Sign-in integration is required.",
  "route.auth.integration.description":
    "This protected route is available after an external authentication owner is connected.",
  "route.auth.recovering.title": "Recovering the session.",
  "route.auth.required.title": "A session is required.",
  "route.auth.recovering.description":
    "Run recovery to continue checking the existing session.",
  "route.auth.required.description":
    "This protected route demonstrates the authentication integration seam.",
  "route.documentTitle": "{title} · {appName}",
  "chunk.checking": "Checking the new release information.",
  "chunk.reloadOnce": "Switching to the new version once.",
  "chunk.failure.title": "The page assets could not be recovered.",
  "chunk.failure.description":
    "If the problem continues, check deployment status and support information.",
  "page.notFound.title": "Page not found.",
  "page.notFound.description": "Check the address or return to the start page.",
  "template.breadcrumb": "Current location",
  "template.relatedInformation": "Related information",
  "template.searchAndFilter": "Search and filters",
  "template.pagination": "Pagination",
  "template.summary": "Summary information",
  "template.dangerActions": "Dangerous actions",
  "template.supportReference": "Support reference: {reference}",
  "form.errorSummary": "Review the entered information.",
  "form.unsaved.title": "You have unsaved changes.",
  "form.unsaved.description":
    "The entered information will be lost if you leave this page.",
  "form.validation.required": "This field is required.",
  "form.validation.tooSmall": "This value is too short.",
  "form.validation.tooBig": "This value is too long.",
  "form.validation.invalidType": "Check the input type.",
  "form.validation.invalidFormat": "Check the input format.",
  "form.validation.invalidValue": "Choose an allowed value.",
  "form.validation.unknown": "Check the entered value.",
  "form.validation.retry": "Review the entered values.",
  "form.validation.unknownField":
    "The server reported an unrecognized input field.",
  "form.validation.configuration": "Review the input configuration.",
  "form.conflict":
    "Another update conflicts with this change. Your input has been preserved.",
  "form.unavailable": "The change could not be saved. Try again shortly.",
  "form.remaining": "{count} characters remaining",
  "toast.region": "Notifications",
  "error.network_unreachable": "The network is unavailable.",
  "error.request_timeout": "The request timed out.",
  "error.auth_required": "Sign in to continue.",
  "error.auth_integration_failure": "Sign-in integration is unavailable.",
  "error.forbidden": "You are not allowed to perform this action.",
  "error.not_found": "The requested item could not be found.",
  "error.rate_limited": "Too many requests were made. Try again shortly.",
  "error.server_failure": "The request could not be completed.",
  "error.chunk_load_failure": "The new page assets could not be loaded.",
  "error.build_mismatch": "The active build does not match this page.",
  "error.config_mismatch": "The runtime configuration does not match this page.",
  "error.api_contract_mismatch": "The API contract does not match this page.",
  "error.release_mismatch": "The active release does not match this page.",
  "error.asset_mismatch": "The page assets do not match this release.",
  "error.render_failure": "The page could not be displayed.",
  "error.unknown_failure": "An unexpected problem occurred.",
  "boot.failure.title": "The application could not start.",
  "boot.field.error": "Error",
  "boot.field.code": "Code",
  "boot.field.build": "Build",
  "boot.field.configSchema": "Configuration schema",
  "boot.field.release": "Release",
  "boot.supportReference": "Support reference: {reference}",
 } as const satisfies Record<keyof typeof PLATFORM_KO_MESSAGES, string>;
 export const EN_MESSAGES = {
  ...PLATFORM_EN_MESSAGES,
  ...INSTALLED_MESSAGE_CATALOGS["en-US"],
 } as const satisfies Record<MessageKey, string>;
 export const MESSAGE_CATALOGS = Object.freeze({
  "ko-KR": KO_MESSAGES,
  "en-US": EN_MESSAGES,
  "ar-EG": EN_MESSAGES,
 });
@@ -0,0 +1,96 @@
 import { normalizeLocale, type SupportedLocale } from "./message-contract.js";
 const FORMAT_FALLBACK = "—";
 export type DateFormatStyle = "short" | "medium" | "long";
 export function formatDate(
  locale: SupportedLocale,
  value: Date | number,
  options: Readonly<{
    dateStyle?: DateFormatStyle;
    timeZone?: string;
  }> = {},
 ): string {
  try {
    const date = value instanceof Date ? value : new Date(value);
    if (Number.isNaN(date.getTime())) return FORMAT_FALLBACK;
    return new Intl.DateTimeFormat(normalizeLocale(locale), {
      dateStyle: options.dateStyle ?? "medium",
      timeZone: options.timeZone ?? "UTC",
    }).format(date);
  } catch {
    return FORMAT_FALLBACK;
  }
 }
 export function formatNumber(
  locale: SupportedLocale,
  value: number,
  options: Readonly<{
    style?: "decimal" | "percent";
    maximumFractionDigits?: number;
  }> = {},
 ): string {
  try {
    if (!Number.isFinite(value)) return FORMAT_FALLBACK;
    return new Intl.NumberFormat(normalizeLocale(locale), options).format(value);
  } catch {
    return FORMAT_FALLBACK;
  }
 }
 export function formatRelativeTime(
  locale: SupportedLocale,
  value: number,
  unit: Intl.RelativeTimeFormatUnit,
 ): string {
  try {
    if (!Number.isFinite(value)) return FORMAT_FALLBACK;
    return new Intl.RelativeTimeFormat(normalizeLocale(locale), {
      numeric: "auto",
    }).format(value, unit);
  } catch {
    return FORMAT_FALLBACK;
  }
 }
 export function formatList(
  locale: SupportedLocale,
  values: readonly string[],
 ): string {
  try {
    return new Intl.ListFormat(normalizeLocale(locale), {
      style: "long",
      type: "conjunction",
    }).format(values);
  } catch {
    return values.join(", ");
  }
 }
 export function selectPlural(
  locale: SupportedLocale,
  value: number,
  choices: Readonly<
    Partial<Record<Intl.LDMLPluralRule, string>> & { other: string }
  >,
 ): string {
  try {
    if (!Number.isFinite(value)) return choices.other;
    return choices[
      new Intl.PluralRules(normalizeLocale(locale)).select(value)
    ] ?? choices.other;
  } catch {
    return choices.other;
  }
 }
 export function selectMessage(
  value: string,
  choices: Readonly<Record<string, string> & { other: string }>,
 ): string {
  return choices[value] ?? choices.other;
 }
 export { FORMAT_FALLBACK };
@@ -0,0 +1,29 @@
 export { LocaleProvider, useLocale } from "./locale-provider.js";
 export {
  catalogKeys,
  fallbackMessage,
  formatMessage,
  localeDirection,
  MESSAGE_KEY_ALIASES,
  messagePlaceholders,
  normalizeLocale,
  resolveMessage,
  SUPPORTED_LOCALES,
 } from "./message-contract.js";
 export type {
  MessageArguments,
  MessageParameters,
  ParameterlessMessageKey,
  SupportedLocale,
  TextDirection,
 } from "./message-contract.js";
 export type { MessageKey } from "./catalog.js";
 export {
  FORMAT_FALLBACK,
  formatDate,
  formatList,
  formatNumber,
  formatRelativeTime,
  selectMessage,
  selectPlural,
 } from "./formatters.js";
@@ -0,0 +1,118 @@
 import {
  createContext,
  useContext,
  useEffect,
  useMemo,
  useState,
 } from "react";
 import {
  formatDate,
  formatList,
  formatNumber,
  formatRelativeTime,
  selectMessage,
  selectPlural,
 } from "./formatters.js";
 import {
  formatMessage,
  localeDirection,
  normalizeLocale,
  resolveMessage,
  type MessageArguments,
  type SupportedLocale,
  type TextDirection,
 } from "./message-contract.js";
 import type { MessageKey } from "./catalog.js";
 type LocaleContextValue = Readonly<{
  locale: SupportedLocale;
  direction: TextDirection;
  setLocale(locale: SupportedLocale): void;
  message<Key extends MessageKey>(
    key: Key,
    ...args: MessageArguments<Key>
  ): string;
  resolve(key: string): string;
  date(
    value: Date | number,
    options?: Parameters<typeof formatDate>[2],
  ): string;
  number(value: number, options?: Parameters<typeof formatNumber>[2]): string;
  relativeTime(
    value: number,
    unit: Intl.RelativeTimeFormatUnit,
  ): string;
  list(values: readonly string[]): string;
  plural(
    value: number,
    choices: Parameters<typeof selectPlural>[2],
  ): string;
  select(
    value: string,
    choices: Readonly<Record<string, string> & { other: string }>,
  ): string;
 }>;
 const DEFAULT_LOCALE = "ko-KR" as const;
 const DEFAULT_CONTEXT: LocaleContextValue = Object.freeze({
  locale: DEFAULT_LOCALE,
  direction: "ltr",
  setLocale() {},
  message: (key, ...args) => formatMessage(DEFAULT_LOCALE, key, ...args),
  resolve: (key) => resolveMessage(DEFAULT_LOCALE, key),
  date: (value, options) => formatDate(DEFAULT_LOCALE, value, options),
  number: (value, options) => formatNumber(DEFAULT_LOCALE, value, options),
  relativeTime: (value, unit) =>
    formatRelativeTime(DEFAULT_LOCALE, value, unit),
  list: (values) => formatList(DEFAULT_LOCALE, values),
  plural: (value, choices) => selectPlural(DEFAULT_LOCALE, value, choices),
  select: (value, choices) => selectMessage(value, choices),
 });
 const LocaleContext = createContext<LocaleContextValue>(DEFAULT_CONTEXT);
 export function LocaleProvider({
  children,
  initialLocale = "ko-KR",
 }: Readonly<{
  children: React.ReactNode;
  initialLocale?: SupportedLocale;
 }>) {
  const [locale, setLocaleState] = useState<SupportedLocale>(() =>
    normalizeLocale(initialLocale),
  );
  const direction = localeDirection(locale);
  useEffect(() => {
    document.documentElement.lang = locale;
    document.documentElement.dir = direction;
  }, [direction, locale]);
  const value = useMemo<LocaleContextValue>(
    () => ({
      locale,
      direction,
      setLocale: setLocaleState,
      message: (key, ...args) => formatMessage(locale, key, ...args),
      resolve: (key) => resolveMessage(locale, key),
      date: (dateValue, options) => formatDate(locale, dateValue, options),
      number: (numberValue, options) =>
        formatNumber(locale, numberValue, options),
      relativeTime: (relativeValue, unit) =>
        formatRelativeTime(locale, relativeValue, unit),
      list: (values) => formatList(locale, values),
      plural: (pluralValue, choices) =>
        selectPlural(locale, pluralValue, choices),
      select: (selectValue, choices) => selectMessage(selectValue, choices),
    }),
    [direction, locale],
  );
  return (
    <LocaleContext.Provider value={value}>{children}</LocaleContext.Provider>
  );
 }
 export function useLocale(): LocaleContextValue {
  return useContext(LocaleContext);
 }
@@ -0,0 +1,135 @@
 import {
  EN_MESSAGES,
  KO_MESSAGES,
  MESSAGE_CATALOGS,
  type MessageKey,
 } from "./catalog.js";
 export const SUPPORTED_LOCALES = Object.freeze([
  "ko-KR",
  "en-US",
  "en-XA",
  "ar-EG",
 ] as const);
 export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
 export type TextDirection = "ltr" | "rtl";
 export type MessageParameters = Readonly<{
  "action.closeNamed": { title: string };
  "action.alertCloseNamed": { title: string };
  "route.loadingNamed": { title: string };
  "route.documentTitle": { title: string; appName: string };
  "template.supportReference": { reference: string };
  "form.remaining": { count: number };
  "boot.supportReference": { reference: string };
 }>;
 export type ParameterlessMessageKey = Exclude<
  MessageKey,
  keyof MessageParameters
 >;
 export type MessageArguments<Key extends MessageKey> =
  Key extends keyof MessageParameters
    ? [parameters: MessageParameters[Key]]
    : [parameters?: never];
 const PLACEHOLDER_PATTERN = /\{([a-zA-Z][a-zA-Z0-9]*)\}/g;
 const FALLBACK_LOCALE = "ko-KR" as const;
 export const MESSAGE_KEY_ALIASES = Object.freeze({
  "action.login": "action.reauth",
  "async.pending": "common.processing",
 } as const satisfies Readonly<Record<string, MessageKey>>);
 export function normalizeLocale(locale: string): SupportedLocale {
  if ((SUPPORTED_LOCALES as readonly string[]).includes(locale)) {
    return locale as SupportedLocale;
  }
  const language = locale.split("-")[0]?.toLowerCase();
  if (language === "ko") return "ko-KR";
  if (language === "ar") return "ar-EG";
  if (language === "en") return "en-US";
  return FALLBACK_LOCALE;
 }
 export function localeDirection(locale: SupportedLocale): TextDirection {
  return locale === "ar-EG" ? "rtl" : "ltr";
 }
 export function messagePlaceholders(template: string): readonly string[] {
  return Object.freeze(
    [...template.matchAll(PLACEHOLDER_PATTERN)].map((match) => match[1] ?? ""),
  );
 }
 export function resolveMessage(
  locale: string,
  key: string,
  parameters?: Readonly<Record<string, string | number>>,
 ): string {
  const normalized = normalizeLocale(locale);
  const sourceLocale: keyof typeof MESSAGE_CATALOGS =
    normalized === "en-XA" ? "en-US" : normalized;
  const catalog =
    MESSAGE_CATALOGS[sourceLocale] ??
    MESSAGE_CATALOGS[FALLBACK_LOCALE];
  const fallback = KO_MESSAGES["common.unavailable"];
  const canonicalKey =
    MESSAGE_KEY_ALIASES[key as keyof typeof MESSAGE_KEY_ALIASES] ?? key;
  const template = catalog[canonicalKey as MessageKey] ?? fallback;
  const placeholders = messagePlaceholders(template);
  if (
    placeholders.some(
      (placeholder) =>
        parameters?.[placeholder] === undefined ||
        parameters?.[placeholder] === null,
    )
  ) {
    return fallback;
  }
  const formatted = template.replace(
    PLACEHOLDER_PATTERN,
    (_, placeholder: string) => String(parameters?.[placeholder] ?? ""),
  );
  return normalized === "en-XA" ? pseudoLocalize(formatted) : formatted;
 }
 export function formatMessage<Key extends MessageKey>(
  locale: string,
  key: Key,
  ...args: MessageArguments<Key>
 ): string {
  return resolveMessage(
    locale,
    key,
    args[0] as Readonly<Record<string, string | number>> | undefined,
  );
 }
 function pseudoLocalize(value: string): string {
  const expanded = value.replace(/[A-Za-z]/g, (character) => {
    const replacements: Readonly<Record<string, string>> = {
      a: "á",
      e: "é",
      i: "í",
      o: "ó",
      u: "ú",
      A: "Á",
      E: "É",
      I: "Í",
      O: "Ó",
      U: "Ú",
    };
    return replacements[character] ?? character;
  });
  return `［${expanded} ···］`;
 }
 export function catalogKeys(
  locale: "ko-KR" | "en-US" | "ar-EG",
 ): MessageKey[] {
  return Object.keys(MESSAGE_CATALOGS[locale]).sort() as MessageKey[];
 }
 export function fallbackMessage() {
  return EN_MESSAGES["common.unavailable"];
 }
@@ -12,20 +12,22 @@ import {
  MenuIcon,
  Select,
 } from "../design-system/index.js";
 import { useLocale } from "../i18n/index.js";
 import { useSession } from "../providers/session-provider.jsx";
 import { useTheme } from "../providers/theme-provider.jsx";
-const SESSION_LABELS = Object.freeze({
+const SESSION_MESSAGE_KEYS = Object.freeze({
-  authenticated: "인증됨",
+  authenticated: "shell.session.authenticated",
-  unauthenticated: "로그인 전",
+  unauthenticated: "shell.session.unauthenticated",
-  "recovery-pending": "복구 대기",
+  "recovery-pending": "shell.session.recoveryPending",
-  "integration-failed": "연동 필요",
+  "integration-failed": "shell.session.integrationFailed",
 });
 export function AppShell() {
  const location = useLocation();
  const { sessionState, beginSignIn, signOut, recover } = useSession();
  const { preference, setPreference } = useTheme();
  const { locale, setLocale, message } = useLocale();
  const [navigationOpen, setNavigationOpen] = useState(false);
  const [sessionActionPending, setSessionActionPending] = useState(false);
  const [sessionActionFailed, setSessionActionFailed] = useState(false);
@@ -56,20 +58,20 @@ export function AppShell() {
  const sessionActionLabel =
    sessionState === "authenticated"
-      ? "로그아웃"
+      ? message("action.signOut")
      : sessionState === "recovery-pending"
-        ? "세션 복구"
+        ? message("action.recoverSession")
-        : "로그인";
+        : message("action.reauth");
  const integrationAvailable = sessionState !== "integration-failed";
  return (
    <div className="app-shell">
      <a className="skip-link" href="#main-content">
-        본문으로 건너뛰기
+        {message("shell.skipToContent")}
      </a>
      <header className="app-shell__header">
        <IconButton
-          accessibleName="메뉴"
+          accessibleName={message("shell.menu")}
          className="app-shell__menu-button"
          aria-controls="mobile-primary-navigation"
          aria-expanded={navigationOpen}
@@ -79,17 +81,17 @@ export function AppShell() {
          <MenuIcon />
        </IconButton>
        <NavLink className="app-shell__brand" to={routePath("APP_HOME")}>
-          Frontend Skeleton
+          {message("common.appName")}
        </NavLink>
        <div className="app-shell__session">
          <Select
            className="theme-selector"
            id="theme-preference"
-            label="색상 테마"
+            label={message("shell.theme")}
            options={[
-              { value: "system", label: "시스템 테마" },
+              { value: "system", label: message("shell.theme.system") },
-              { value: "light", label: "라이트 테마" },
+              { value: "light", label: message("shell.theme.light") },
-              { value: "dark", label: "다크 테마" },
+              { value: "dark", label: message("shell.theme.dark") },
            ]}
            value={preference}
            onChange={(event) =>
@@ -100,8 +102,27 @@ export function AppShell() {
              )
            }
          />
          <Select
            className="locale-selector"
            id="locale-preference"
            label={message("shell.locale")}
            options={[
              { value: "ko-KR", label: message("shell.locale.ko") },
              { value: "en-US", label: message("shell.locale.en") },
              { value: "en-XA", label: message("shell.locale.pseudo") },
              { value: "ar-EG", label: message("shell.locale.rtl") },
            ]}
            value={locale}
            onChange={(event) =>
              setLocale(
                /** @type {import("../i18n/index.js").SupportedLocale} */ (
                  event.currentTarget.value
                ),
              )
            }
          />
          <span className="session-status" data-state={sessionState}>
-            {SESSION_LABELS[sessionState]}
+            {message(SESSION_MESSAGE_KEYS[sessionState])}
          </span>
          {integrationAvailable ? (
            <Button
@@ -109,24 +130,29 @@ export function AppShell() {
              onClick={() => void runSessionAction()}
              size="compact"
            >
-              {sessionActionPending ? "처리 중…" : sessionActionLabel}
+              {sessionActionPending
                ? message("common.processing")
                : sessionActionLabel}
            </Button>
          ) : null}
        </div>
        {sessionActionFailed ? (
          <p className="app-shell__session-error" role="alert">
-            세션 작업을 완료하지 못했습니다.
+            {message("shell.session.actionFailed")}
          </p>
        ) : null}
      </header>
-      <aside className="app-shell__sidebar" aria-label="사이드바">
+      <aside
        className="app-shell__sidebar"
        aria-label={message("shell.sidebar")}
      >
        <PrimaryNavigation id="primary-navigation" />
      </aside>
      <Drawer
-        closeLabel="메뉴 닫기"
+        closeLabel={message("shell.closeMenu")}
        onClose={() => setNavigationOpen(false)}
        open={navigationOpen}
-        title="메뉴"
+        title={message("shell.menu")}
      >
        <PrimaryNavigation id="mobile-primary-navigation" />
      </Drawer>
@@ -141,8 +167,9 @@ export function AppShell() {
 * @param {{ id: string }} props
 */
 function PrimaryNavigation({ id }) {
  const { resolve, message } = useLocale();
  return (
-    <nav id={id} aria-label="주요 탐색">
+    <nav id={id} aria-label={message("shell.primaryNavigation")}>
      <ul className="app-navigation">
        {NAVIGATION_ROUTES.map((definition) => (
          <li key={definition.routeId}>
@@ -153,7 +180,7 @@ function PrimaryNavigation({ id }) {
              end={definition.path === "/"}
              to={definition.path}
            >
-              {definition.navigationLabel}
+              {resolve(`route.${definition.routeId}.navigation`)}
            </NavLink>
          </li>
        ))}
@@ -2,17 +2,19 @@ import { Link } from "react-router-dom";
 import { routePath } from "../../features/installed-feature-contracts.js";
 import { PageHeader } from "../design-system/index.js";
 import { useLocale } from "../i18n/index.js";
 export default function NotFoundPage() {
  const { message } = useLocale();
  return (
    <section className="ui-page">
      <PageHeader
-        title="페이지를 찾을 수 없습니다."
+        title={message("page.notFound.title")}
-        description="주소를 확인하거나 준비된 시작 화면으로 돌아가세요."
+        description={message("page.notFound.description")}
      />
      <div>
        <Link className="ui-button" to={routePath("APP_HOME")}>
-          홈으로 이동
+          {message("action.goHome")}
        </Link>
      </div>
    </section>
@@ -28,7 +28,8 @@ import {
  RouteBoundary,
 } from "../boundaries/render-error-boundary.jsx";
 import { ChunkRecoveryBoundary } from "../boundaries/chunk-recovery-boundary.js";
-import { PageHeader } from "../design-system/index.js";
+import { Button, PageHeader } from "../design-system/index.js";
 import { LocaleProvider, useLocale } from "../i18n/index.js";
 import { AppShell } from "../layouts/app-shell.jsx";
 import { useApplication } from "../providers/application-provider.js";
 import { SessionProvider, useSession } from "../providers/session-provider.jsx";
@@ -54,6 +55,8 @@ export function useRouteInput(): ParsedRouteInput {
 }
 function RouteLoadingSurface({ definition }: { definition: RouteDefinition }) {
  const { message, resolve } = useLocale();
  const title = resolve(`route.${definition.routeId}.title`);
  return (
    <section
      className="ui-page route-loading"
@@ -62,8 +65,10 @@ function RouteLoadingSurface({ definition }: { definition: RouteDefinition }) {
      data-surface={definition.loadingSurface}
    >
      <div className="ui-skeleton" aria-hidden="true" />
-      <p>화면을 준비하고 있습니다.</p>
+      <p>{message("route.loading")}</p>
-      <span className="visually-hidden">{definition.title} 로딩 중</span>
+      <span className="visually-hidden">
        {message("route.loadingNamed", { title })}
      </span>
    </section>
  );
 }
@@ -73,35 +78,41 @@ function RouteFailureSurface({
 }: {
  definition?: RouteDefinition;
 }) {
  const { message } = useLocale();
  return (
    <section
      className="ui-page"
      data-surface={definition?.errorSurface ?? "route-boundary"}
    >
      <PageHeader
-        title="화면을 표시하지 못했습니다."
+        title={message("route.failure.title")}
-        description="잠시 후 다시 시도해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요."
+        description={message("route.failure.description")}
      />
    </section>
  );
 }
 function InvalidRouteSurface({ code }: { code: string }) {
  const { message } = useLocale();
  return (
    <section className="ui-page" data-surface="invalid-route">
      <PageHeader
-        title="올바르지 않은 주소입니다."
+        title={message("route.invalid.title")}
-        description="주소의 경로 또는 검색 조건을 확인해 주세요."
+        description={message("route.invalid.description")}
      />
-      <p data-route-error={code}>안전한 탐색 링크를 사용해 주세요.</p>
+      <p data-route-error={code}>{message("route.invalid.action")}</p>
    </section>
  );
 }
 function RouteLifecycle({ definition }: { definition: RouteDefinition }) {
  const location = useLocation();
  const { message, resolve } = useLocale();
  useEffect(() => {
-    document.title = `${definition.title} · Frontend Skeleton`;
+    document.title = message("route.documentTitle", {
      title: resolve(`route.${definition.routeId}.title`),
      appName: message("common.appName"),
    });
    const main = document.getElementById("main-content");
    main?.focus({ preventScroll: true });
    try {
@@ -111,7 +122,7 @@ function RouteLifecycle({ definition }: { definition: RouteDefinition }) {
    } catch {
      // Non-browser test hosts may not implement scrolling.
    }
-  }, [definition, location.key, location.pathname]);
+  }, [definition, location.key, location.pathname, message, resolve]);
  return null;
 }
@@ -146,6 +157,7 @@ function ProtectedRoute({
 }) {
  const location = useLocation();
  const { sessionState, beginSignIn, recover } = useSession();
  const { message } = useLocale();
  const [pending, setPending] = useState(false);
  const [failed, setFailed] = useState(false);
  const decision = decideRouteAccess(routeId, sessionState);
@@ -173,8 +185,8 @@ function ProtectedRoute({
    return (
      <section className="ui-page" data-surface="auth-integration-required">
        <PageHeader
-          title="로그인 연동이 필요합니다."
+          title={message("route.auth.integration.title")}
-          description="외부 인증 소유자가 연결되면 이 보호 라우트를 사용할 수 있습니다."
+          description={message("route.auth.integration.description")}
        />
      </section>
    );
@@ -183,24 +195,30 @@ function ProtectedRoute({
  return (
    <section className="ui-page" data-surface="authentication-required">
      <PageHeader
-        title={recovering ? "세션을 복구하고 있습니다." : "세션이 필요합니다."}
+        title={
          recovering
            ? message("route.auth.recovering.title")
            : message("route.auth.required.title")
        }
        description={
          recovering
-            ? "기존 세션 확인을 계속하려면 복구를 실행하세요."
+            ? message("route.auth.recovering.description")
-            : "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."
+            : message("route.auth.required.description")
        }
      />
-      <button
+      <Button
        className="ui-button"
        type="button"
        disabled={pending}
        onClick={() => void continueSession()}
      >
-        {pending ? "처리 중…" : recovering ? "세션 복구" : "로그인 시작"}
+        {pending
-      </button>
+          ? message("common.processing")
          : recovering
            ? message("action.recoverSession")
            : message("action.signIn")}
      </Button>
      {failed ? (
        <p className="ui-terminal-error" role="alert">
-          세션 작업을 완료하지 못했습니다.
+          {message("shell.session.actionFailed")}
        </p>
      ) : null}
    </section>
@@ -300,10 +318,12 @@ export function AppRouter({
    [basename, buildId],
  );
  return (
-    <ThemeProvider>
+    <LocaleProvider>
-      <SessionProvider>
+      <ThemeProvider>
-        <RouterProvider router={router} />
+        <SessionProvider>
-      </SessionProvider>
+          <RouterProvider router={router} />
-    </ThemeProvider>
+        </SessionProvider>
      </ThemeProvider>
    </LocaleProvider>
  );
 }
@@ -131,11 +131,13 @@
    margin-inline-start: auto;
  }
-  .theme-selector {
+  .theme-selector,
  .locale-selector {
    display: block;
  }
-  .theme-selector .ui-field__label {
+  .theme-selector .ui-field__label,
  .locale-selector .ui-field__label {
    position: absolute;
    width: 1px;
    height: 1px;
@@ -147,13 +149,18 @@
    border: 0;
  }
-  .theme-selector .ui-field__input {
+  .theme-selector .ui-field__input,
  .locale-selector .ui-field__input {
    min-height: var(--size-control-sm);
    max-width: 8.5rem;
    padding: 0.35rem 2rem 0.35rem 0.65rem;
    cursor: pointer;
  }
  .locale-selector .ui-field__input {
    max-width: 7rem;
  }
  .app-shell__session-error {
    position: absolute;
    top: calc(100% + 0.25rem);
@@ -1340,6 +1347,10 @@
    display: none;
  }
  .app-shell__session .theme-selector {
    display: none;
  }
  .app-shell__brand {
    display: none;
  }
@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import { PageHeader } from "../components/page-header.jsx";
 import { Button } from "../components/ui/button.jsx";
 import { useLocale } from "../i18n/index.js";
 export type PageHeading = Readonly<{
  title: string;
@@ -36,10 +37,14 @@ export type PageTemplateSlots = Readonly<{
 }>;
 export function StandardPage(props: PageTemplateSlots) {
  const { message } = useLocale();
  return (
    <article className="ui-page page-template page-template--standard">
      {props.breadcrumb ? (
-        <nav className="page-template__breadcrumb" aria-label="현재 위치">
+        <nav
          className="page-template__breadcrumb"
          aria-label={message("template.breadcrumb")}
        >
          {props.breadcrumb}
        </nav>
      ) : null}
@@ -64,7 +69,10 @@ export function StandardPage(props: PageTemplateSlots) {
      >
        <div className="page-template__content">{props.children}</div>
        {props.aside ? (
-          <aside className="page-template__aside" aria-label="관련 정보">
+          <aside
            className="page-template__aside"
            aria-label={message("template.relatedInformation")}
          >
            {props.aside}
          </aside>
        ) : null}
@@ -83,6 +91,7 @@ export function CollectionPage(
      pagination?: ReactNode;
    }>,
 ) {
  const { message } = useLocale();
  return (
    <StandardPage
      {...props}
@@ -92,7 +101,7 @@ export function CollectionPage(
          {props.toolbar ? (
            <section
              className="collection-page__toolbar"
-              aria-label="검색과 필터"
+              aria-label={message("template.searchAndFilter")}
            >
              {props.toolbar}
            </section>
@@ -117,7 +126,10 @@ export function CollectionPage(
    >
      <div className="collection-page__results">{props.children}</div>
      {props.pagination ? (
-        <nav className="collection-page__pagination" aria-label="페이지 탐색">
+        <nav
          className="collection-page__pagination"
          aria-label={message("template.pagination")}
        >
          {props.pagination}
        </nav>
      ) : null}
@@ -132,16 +144,23 @@ export function DetailPage(
      destructiveAction?: ReactNode;
    }>,
 ) {
  const { message } = useLocale();
  return (
    <StandardPage {...props}>
      {props.metadata ? (
-        <section className="detail-page__metadata" aria-label="요약 정보">
+        <section
          className="detail-page__metadata"
          aria-label={message("template.summary")}
        >
          {props.metadata}
        </section>
      ) : null}
      <div className="detail-page__sections">{props.children}</div>
      {props.destructiveAction ? (
-        <section className="detail-page__danger" aria-label="위험 작업">
+        <section
          className="detail-page__danger"
          aria-label={message("template.dangerActions")}
        >
          {props.destructiveAction}
        </section>
      ) : null}
@@ -190,6 +209,7 @@ export function StatusPage(
    supportReference?: string;
  }>,
 ) {
  const { message } = useLocale();
  return (
    <section
      className={`ui-page page-template status-page status-page--${props.variant}`}
@@ -208,7 +228,9 @@ export function StatusPage(
      ) : null}
      {props.supportReference ? (
        <p className="status-page__support">
-          지원 참조: <code>{props.supportReference}</code>
+          {message("template.supportReference", {
            reference: props.supportReference,
          })}
        </p>
      ) : null}
    </section>
@@ -50,7 +50,9 @@ describe("async UI state matrix", () => {
    render(<AsyncSurface state={state}>existing content</AsyncSurface>);
    expect(screen.getByText("existing content")).toBeVisible();
-    expect(screen.getByRole("status")).toHaveTextContent("refreshing");
+    expect(screen.getByRole("status")).toHaveTextContent(
      "최신 정보를 확인하고 있습니다.",
    );
  });
  it("connects stale retry and conflict resolution to real callbacks", async () => {
@@ -60,7 +60,9 @@ describe("chunk recovery boundary classification", () => {
      </FeatureBoundary>,
    );
-    expect(screen.getByRole("alert")).toHaveTextContent("error.render_failure");
+    expect(screen.getByRole("alert")).toHaveTextContent(
      "화면을 표시하지 못했습니다.",
    );
    expect(recover).not.toHaveBeenCalled();
  });
 });
@@ -189,7 +189,7 @@ describe("design-system platform interactions", () => {
    await user.click(screen.getByRole("button", { name: "중복" }));
    expect(screen.getByText("×2")).toBeVisible();
    await user.click(screen.getByRole("button", { name: "다섯 개" }));
-    const region = screen.getByRole("region", { name: "Notifications" });
+    const region = screen.getByRole("region", { name: "알림" });
    expect(within(region).getAllByRole("article")).toHaveLength(3);
    expect(within(region).queryByText("알림 0")).not.toBeInTheDocument();
    expect(within(region).getByText("알림 4")).toBeVisible();
@@ -0,0 +1,120 @@
 // @vitest-environment jsdom
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { useState } from "react";
 import { describe, expect, it } from "vitest";
 import {
  Button,
  Drawer,
  Pagination,
  Tabs,
 } from "../../src/presentation/design-system/index.js";
 import {
  LocaleProvider,
  useLocale,
  type SupportedLocale,
 } from "../../src/presentation/i18n/index.js";
 function LocaleHarness() {
  const { direction, locale, message, setLocale } = useLocale();
  const [drawerOpen, setDrawerOpen] = useState(false);
  return (
    <>
      <label htmlFor="test-locale">{message("shell.locale")}</label>
      <select
        id="test-locale"
        onChange={(event) =>
          setLocale(event.currentTarget.value as SupportedLocale)
        }
        value={locale}
      >
        <option value="ko-KR">한국어</option>
        <option value="en-US">English</option>
        <option value="ar-EG">RTL</option>
      </select>
      <output>{`${locale}:${direction}`}</output>
      <Button onClick={() => setDrawerOpen(true)}>
        {message("shell.menu")}
      </Button>
      <Drawer
        closeLabel={message("shell.closeMenu")}
        onClose={() => setDrawerOpen(false)}
        open={drawerOpen}
        title={message("shell.menu")}
      >
        content
      </Drawer>
    </>
  );
 }
 describe("locale provider runtime", () => {
  it("switches copy and synchronizes the document language and direction", async () => {
    const user = userEvent.setup();
    render(
      <LocaleProvider>
        <LocaleHarness />
      </LocaleProvider>,
    );
    expect(document.documentElement).toHaveAttribute("lang", "ko-KR");
    await user.selectOptions(screen.getByLabelText("언어"), "en-US");
    expect(screen.getByLabelText("Language")).toHaveValue("en-US");
    expect(document.documentElement).toHaveAttribute("lang", "en-US");
    expect(document.documentElement).toHaveAttribute("dir", "ltr");
    await user.selectOptions(screen.getByLabelText("Language"), "ar-EG");
    expect(document.documentElement).toHaveAttribute("lang", "ar-EG");
    expect(document.documentElement).toHaveAttribute("dir", "rtl");
    await user.click(screen.getByRole("button", { name: "Menu" }));
    expect(screen.getByRole("dialog", { name: "Menu" })).toHaveAttribute(
      "open",
    );
  });
  it("reverses horizontal tab focus semantics in RTL", async () => {
    const user = userEvent.setup();
    render(
      <LocaleProvider initialLocale="ar-EG">
        <Tabs
          activation="manual"
          label="sections"
          tabs={[
            { id: "one", label: "One", panel: "One panel" },
            { id: "two", label: "Two", panel: "Two panel" },
            { id: "three", label: "Three", panel: "Three panel" },
          ]}
        />
      </LocaleProvider>,
    );
    const first = screen.getByRole("tab", { name: "One" });
    first.focus();
    await user.keyboard("{ArrowRight}");
    expect(screen.getByRole("tab", { name: "Three" })).toHaveFocus();
    await user.keyboard("{ArrowLeft}");
    expect(first).toHaveFocus();
  });
  it("keeps pagination semantics while direction-aware icons remain decorative", () => {
    render(
      <LocaleProvider initialLocale="ar-EG">
        <Pagination
          label="pages"
          nextLabel="Next page"
          onChange={() => {}}
          page={2}
          pageCount={3}
          pageLabel={(page) => `Page ${page}`}
          previousLabel="Previous page"
        />
      </LocaleProvider>,
    );
    expect(
      screen.getByRole("button", { name: "Previous page" }),
    ).toBeEnabled();
    expect(screen.getByRole("button", { name: "Next page" })).toBeEnabled();
    expect(screen.queryByRole("img")).not.toBeInTheDocument();
  });
 });
@@ -86,7 +86,7 @@ describe("page template slot contracts", () => {
      />,
    );
    expect(screen.getByRole("heading", { level: 1, name: "Offline" })).toBeVisible();
-    expect(screen.getByText("SAFE-123")).toBeVisible();
+    expect(screen.getByText(/SAFE-123/)).toBeVisible();
    expect(document.body).not.toHaveTextContent("stack");
  });
 });
@@ -28,7 +28,9 @@ describe("render recovery boundaries", () => {
      </FeatureBoundary>,
    );
-    expect(screen.getByRole("alert")).toHaveTextContent("error.render_failure");
+    expect(screen.getByRole("alert")).toHaveTextContent(
      "화면을 표시하지 못했습니다.",
    );
    expect(onRenderFailure).toHaveBeenCalledWith({
      routeId: "APP_HOME",
      buildId: "build-a",
@@ -83,7 +85,7 @@ describe("render recovery boundaries", () => {
      </FeatureBoundary>,
    );
    shouldThrow = false;
-    await user.click(screen.getByRole("button", { name: "retry" }));
+    await user.click(screen.getByRole("button", { name: "다시 시도" }));
    view.rerender(
      <FeatureBoundary routeId="APP_HOME" buildId="build-a">
        <Recoverable />
@@ -0,0 +1,41 @@
 import { expect, test } from "@playwright/test";
 test("switches the shell locale and keeps pseudo-locale copy within compact layout", async ({
  page,
 }) => {
  await page.setViewportSize({ width: 320, height: 720 });
  await page.goto("/");
  const locale = page.getByRole("combobox", { name: "언어" });
  await locale.selectOption("en-US");
  await expect(page.locator("html")).toHaveAttribute("lang", "en-US");
  await expect(page.locator("html")).toHaveAttribute("dir", "ltr");
  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
  await page.getByRole("combobox", { name: "Language" }).selectOption("en-XA");
  await expect(page.locator("html")).toHaveAttribute("lang", "en-XA");
  const dimensions = await page.evaluate(() => ({
    clientWidth: document.documentElement.clientWidth,
    scrollWidth: document.documentElement.scrollWidth,
  }));
  expect(dimensions.scrollWidth).toBeLessThanOrEqual(dimensions.clientWidth);
  await expect(page.getByRole("button", { name: /Ménú/ })).toBeVisible();
 });
 test("applies RTL to the shell and modal navigation without changing action semantics", async ({
  page,
 }) => {
  await page.setViewportSize({ width: 390, height: 844 });
  await page.goto("/");
  await page.getByRole("combobox", { name: "언어" }).selectOption("ar-EG");
  await expect(page.locator("html")).toHaveAttribute("lang", "ar-EG");
  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");
  const trigger = page.getByRole("button", { name: "Menu" });
  await trigger.click();
  await expect(page.getByRole("dialog", { name: "Menu" })).toBeVisible();
  await expect(page.getByRole("navigation", { name: "Primary navigation" }))
    .toHaveCount(1);
  await page.keyboard.press("Escape");
  await expect(trigger).toBeFocused();
 });
@@ -72,10 +72,10 @@ describe("reference feature boundary contracts", () => {
      createdAt: "2026-07-26T00:00:00.000Z",
    });
    if (!("id" in model)) throw new Error("expected one model");
-    expect(toReferenceView(model, () => "formatted")).toEqual({
+    expect(toReferenceView(model)).toEqual({
      resourceId: "reference-1",
      title: "Example",
-      createdAtLabel: "formatted",
+      createdAt: "2026-07-26T00:00:00.000Z",
    });
  });
@@ -55,7 +55,7 @@ function inputWith(
      value: {
        resourceId: "created",
        title: name,
-        createdAtLabel: null,
+        createdAt: null,
      },
    }),
    getResource: async (resourceId) => ({
@@ -63,7 +63,7 @@ function inputWith(
      value: {
        resourceId,
        title: "Detail",
-        createdAtLabel: null,
+        createdAt: null,
      },
    }),
    ...overrides,
@@ -90,7 +90,7 @@ describe("reference feature page states", () => {
        {
          resourceId: "reference-1",
          title: "Loaded",
-          createdAtLabel: null,
+          createdAt: null,
        },
      ],
    });
@@ -191,7 +191,7 @@ describe("reference feature page states", () => {
          {
            resourceId: "existing",
            title: "Existing",
-            createdAtLabel: null,
+            createdAt: null,
          },
        ],
      })
@@ -209,7 +209,7 @@ describe("reference feature page states", () => {
          {
            resourceId: "recovered",
            title: "Recovered",
-            createdAtLabel: null,
+            createdAt: null,
          },
        ],
      });
@@ -217,7 +217,9 @@ describe("reference feature page states", () => {
    await screen.findByText("Existing");
    await user.click(screen.getByRole("button", { name: "새로고침" }));
-    expect(await screen.findByText("stale-degraded")).toBeVisible();
+    expect(
      await screen.findByText("기존 정보를 표시하고 있습니다."),
    ).toBeVisible();
    expect(screen.getByText("Existing")).toBeVisible();
    await user.click(screen.getByRole("button", { name: "다시 시도" }));
    expect(await screen.findByText("Recovered")).toBeVisible();
@@ -0,0 +1,5 @@
 export function UnsafeBackendFailure({
  failure,
 }: Readonly<{ failure: { message: string } }>) {
  return <p>{failure.message}</p>;
 }
@@ -0,0 +1,3 @@
 export function HardcodedCommonAction() {
  return <button type="button">다시 시도</button>;
 }
@@ -0,0 +1,3 @@
 export function UnsafeTranslatedMarkup({ value }: Readonly<{ value: string }>) {
  return <p dangerouslySetInnerHTML={{ __html: value }} />;
 }
@@ -0,0 +1,3 @@
 import { formatMessage } from "../../../src/presentation/i18n/index.js";
 formatMessage("ko-KR", "unknown.translation.key");
@@ -0,0 +1,5 @@
 import { formatMessage } from "../../../src/presentation/i18n/index.js";
 formatMessage("en-US", "route.documentTitle");
 formatMessage("en-US", "route.documentTitle", { title: "Missing app name" });
 formatMessage("en-US", "action.retry", { unexpected: "value" });
@@ -0,0 +1,115 @@
 import { describe, expect, it } from "vitest";
 import {
  catalogKeys,
  FORMAT_FALLBACK,
  formatDate,
  formatList,
  formatMessage,
  formatNumber,
  formatRelativeTime,
  localeDirection,
  messagePlaceholders,
  normalizeLocale,
  resolveMessage,
  selectMessage,
  selectPlural,
 } from "../../src/presentation/i18n/index.js";
 import {
  EN_MESSAGES,
  KO_MESSAGES,
  MESSAGE_CATALOGS,
 } from "../../src/presentation/i18n/catalog.js";
 describe("internationalization message contract", () => {
  it("keeps every registered catalog and interpolation contract in parity", () => {
    expect(catalogKeys("en-US")).toEqual(catalogKeys("ko-KR"));
    expect(catalogKeys("ar-EG")).toEqual(catalogKeys("ko-KR"));
    for (const key of catalogKeys("ko-KR")) {
      expect(messagePlaceholders(EN_MESSAGES[key])).toEqual(
        messagePlaceholders(KO_MESSAGES[key]),
      );
    }
    expect(MESSAGE_CATALOGS["ar-EG"]).toBe(EN_MESSAGES);
  });
  it("formats typed parameters and expands the pseudo locale", () => {
    expect(
      formatMessage("en-US", "route.documentTitle", {
        title: "Settings",
        appName: "Skeleton",
      }),
    ).toBe("Settings · Skeleton");
    const pseudo = formatMessage("en-XA", "action.closeNamed", {
      title: "Account",
    });
    expect(pseudo).toMatch(/^［.+ ···］$/);
    expect(pseudo.length).toBeGreaterThan("Close Account".length);
  });
  it("falls back safely for unknown locale, key and missing interpolation", () => {
    expect(normalizeLocale("fr-FR")).toBe("ko-KR");
    expect(resolveMessage("fr-FR", "action.retry")).toBe("다시 시도");
    expect(resolveMessage("en-US", "action.login")).toBe("Sign in");
    expect(resolveMessage("en-US", "backend.stack.trace")).toBe(
      "요청한 문구를 표시할 수 없습니다.",
    );
    expect(resolveMessage("en-US", "action.closeNamed")).toBe(
      "요청한 문구를 표시할 수 없습니다.",
    );
    expect(resolveMessage("en-US", "backend.stack.trace")).not.toContain(
      "backend.stack.trace",
    );
  });
  it("defines direction without inferring it in components", () => {
    expect(localeDirection("ko-KR")).toBe("ltr");
    expect(localeDirection("en-XA")).toBe("ltr");
    expect(localeDirection("ar-EG")).toBe("rtl");
  });
 });
 describe("internationalization formatter contract", () => {
  const instant = new Date("2026-07-26T23:30:00.000Z");
  it("uses an explicit UTC default and deterministic locale formatting", () => {
    expect(formatDate("en-US", instant, { dateStyle: "short" })).toBe(
      "7/26/26",
    );
    expect(
      formatDate("en-US", instant, {
        dateStyle: "short",
        timeZone: "Asia/Seoul",
      }),
    ).toBe("7/27/26");
    expect(formatNumber("en-US", 1234.5)).toBe("1,234.5");
    expect(formatRelativeTime("en-US", -1, "day")).toBe("yesterday");
    expect(formatList("en-US", ["one", "two", "three"])).toBe(
      "one, two, and three",
    );
    expect(selectPlural("en-US", 1, { one: "item", other: "items" })).toBe(
      "item",
    );
    expect(
      selectPlural("en-US", 3, { one: "item", other: "items" }),
    ).toBe("items");
    expect(
      selectMessage("pending", {
        ready: "Ready",
        pending: "Pending",
        other: "Unknown",
      }),
    ).toBe("Pending");
  });
  it("does not throw or expose invalid formatter input", () => {
    expect(formatDate("en-US", Number.NaN)).toBe(FORMAT_FALLBACK);
    expect(formatNumber("en-US", Number.POSITIVE_INFINITY)).toBe(
      FORMAT_FALLBACK,
    );
    expect(
      formatDate("en-US", instant, { timeZone: "not/a-time-zone" }),
    ).toBe(FORMAT_FALLBACK);
  });
 });
Author	SHA1	Message	Date
donghyeon-ka	668bf05b48	feat: add internationalization message platform	2026-07-26 16:17:39 +09:00
donghyeon-ka	b8c0444217	merge: design system platform	2026-07-26 15:49:13 +09:00
		`@@ -0,0 +1,3 @@`
							`import { formatMessage } from "../../../src/presentation/i18n/index.js";`

							`formatMessage("ko-KR", "unknown.translation.key");`