fix(presentation): 예제 화면이 자기 언어를 ko-KR로 밝힌다 (08-07)

문제: LocaleProvider가 <html lang>을 선택한 locale로 바꾸는데, 예제
화면 4개는 의도적으로 catalog 밖이라 본문이 한국어 literal이다.
en-US로 바꾸면 /examples/platform main의 한글 1,013자가 lang="en-US"
아래에 있어 스크린 리더가 영어 규칙으로 읽는다(WCAG 3.1.2).

고른 방법: 리뷰 대안 (B). 예제 화면 루트 section에 lang="ko-KR"을
준다. 예제를 catalog 밖에 둔 결정(VD-06, check-i18n 예외)은 그대로다.
버린 대안: (C) 예제 문구 번역 — 문구 수백 개이고 지울 수 있는 예제다.
예제 안에 중첩 LocaleProvider(ko-KR) — <html lang>을 전역으로 바꾼다.

위험·한계: 예제 안에서 디자인 시스템 컴포넌트가 catalog로 그리는
문구(접근 상태 화면, 오류 문구, 닫기 같은 접근성 이름)는 en-US에서
영어인데 ko-KR 구역 안에 놓인다. 화면 상태 갤러리에 몇 줄 있다. 한국어
본문 전체가 영어 규칙으로 읽히던 것보다 범위가 훨씬 작아 받아들였다.
예제를 번역하기로 하면 (C)로 간다. 눈에 보이는 화면 변화는 없다.

검증:
- RED: i18n.spec.ts 새 테스트가 수정 전 chromium에서 실패
  (Platform composition: lang Expected "ko-KR", Received "").
- GREEN: i18n·accessibility·ui-gallery·platform-overview e2e
  chromium·firefox·webkit 69/69 통과. tests/component 220/220,
  check-i18n PASS, tsc app 통과, eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-07
This commit is contained in:
DongHyeonka
2026-11-01 23:20:31 +09:00
parent dda153b25e
commit ad73e56476
5 changed files with 35 additions and 4 deletions
@@ -9,7 +9,8 @@ export default function AuthExamplePage() {
const { pending, failed, run } = useSessionAction();
return (
<section className="ui-page">
// 08-07. Example copy is Korean in every locale (outside the catalog).
<section className="ui-page" lang="ko-KR">
<PageHeader
title="인증 연동"
description="스켈레톤은 자격 증명을 소유하지 않고 외부 인증 구현이 연결될 포트와 화면 상태만 제공합니다."
@@ -322,7 +322,8 @@ export function PlatformOverviewPage({
).length;
return (
<section className="ui-page">
// 08-07. Example copy is Korean in every locale (outside the catalog).
<section className="ui-page" lang="ko-KR">
<PageHeader
title="플랫폼 구성"
description="이 화면의 모든 값은 설치된 레지스트리에서 렌더 시점에 읽습니다. 손으로 옮겨 적은 숫자가 없으므로 코드가 바뀌면 이 화면도 함께 바뀝니다."
@@ -25,7 +25,8 @@ export default function StateGalleryPage() {
});
return (
<section className="ui-page">
// 08-07. Example copy is Korean in every locale (outside the catalog).
<section className="ui-page" lang="ko-KR">
<PageHeader
title="화면 상태"
description="로딩, 빈 화면, 오류, 인증 필요와 권한 없음 상태가 다음 행동까지 일관되게 안내합니다."
@@ -69,7 +69,8 @@ function UiGalleryContent() {
}
return (
<section className="ui-page">
// 08-07. Example copy is Korean in every locale (outside the catalog).
<section className="ui-page" lang="ko-KR">
<PageHeader
title="UI 구성요소"
description="제품 도메인과 독립적인 공통 컨트롤, 피드백, 표면과 디자인 토큰을 직접 조작할 수 있습니다."
+27
View File
@@ -54,6 +54,33 @@ test("keeps the header selectors as wide as their options in every locale", asyn
}
});
// 08-07. The example screens stay outside the catalog on purpose, so their
// copy is Korean in every locale. Under en-US a screen reader would read that
// copy with English rules unless the screen names its own language.
test("marks the Korean-only example screens as Korean under another locale", async ({
page,
}) => {
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto("/");
await page.getByRole("combobox", { name: "언어" }).selectOption("en-US");
await expect(page.locator("html")).toHaveAttribute("lang", "en-US");
const navigation = page.getByRole("navigation", { name: "Primary navigation" });
for (const label of [
"Platform composition",
"UI components",
"Screen states",
"Authentication",
]) {
await navigation.getByRole("link", { name: label }).click();
await expect(page).toHaveTitle(new RegExp(`^${label} `));
await expect(page.locator("main .ui-page").first(), label).toHaveAttribute(
"lang",
"ko-KR",
);
}
});
test("applies RTL to the shell and modal navigation without changing action semantics", async ({
page,
}) => {