fix(i18n): 화면 문구 literal 검사를 ESLint 선택자로 옮긴다 (0929/08-02)

문제: `check:i18n`은 화면 파일 전체에 `/[가-힣]/`를 돌린다. 한국어 주석
한 줄에 실패하고, 영어 JSX 문구와 영어 접근성 이름은 통과한다. 샘플
화면에도 영어 literal이 이미 있었다(목록 h1 "Reference feature",
`limit {n}`, 목록 aria-label, 상세 "DetailPage"·"Resource ID"·"Created",
폼·상태 eyebrow). ko-KR 사용자에게 영어 문구와 스크린리더 이름이 섞인다.

고른 방법: (B) 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로
옮긴다(`eslint.config.ts`의 `screenTextSelectors`).
- 대상: 글자(`\p{L}`)가 든 `JSXText`, 표시·접근성 속성(`aria-label`,
  `aria-description`, `aria-roledescription`, `aria-valuetext`,
  `aria-placeholder`, `title`, `placeholder`, `alt`, `label`)의 문자열
  literal, 그리고 `{"..."}` 형태의 같은 literal. 주석은 AST에 없어 빠진다.
  구두점·숫자만 있는 문구는 통과한다.
- 범위(4.3절 "화면 코드"): 지난 `check:i18n`과 같은 폴더다. 공통 UI
  폴더와 `src/features/*/presentation`. 컴포넌트 갤러리
  `src/presentation/examples`는 지금처럼 뺀다. stories(`*.stories.tsx`)는
  workshop 코드라 뺀다. 테스트는 이 폴더 밖이라 대상이 아니다.
- 이 항목은 일반 `no-restricted-syntax` 목록을 대체하므로 FE-OC-019
  선택자(raw HTML, script 생성)를 함께 싣는다.
- `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다.
  raw HTML은 원래 전역 FE-OC-019 ESLint 규칙이 거절한다.
- `check:i18n:fixture`는 ESLint Node API로 같은 규칙을 fixture 트리에도
  돌린다. forbidden 파일은 하나하나 거절돼야 하고(아니면 종료 코드 2),
  새 `tests/fixtures/i18n/allowed` 트리(한국어 주석, 구두점, catalog
  문구)는 통과해야 한다(거절되면 종료 코드 2). 게이트 기대값(종료 1,
  "I18n contract failed:")은 그대로다.
- fixture 추가: allowed `korean-comment.tsx`, forbidden
  `english-jsx-text.tsx`, `english-accessible-name.tsx`.
- 샘플의 영어 literal 11곳을 catalog로 옮겼다. 새 키 10개
  (`reference.list.title`·`filterLimit`·`filterTags`·`resources`,
  `reference.detail.eyebrow`·`titlePending`·`resourceId`·`createdAt`,
  `reference.form.eyebrow`, `reference.status.eyebrow`). en-US 값은
  예전 영어 문구 그대로라 en-US 화면은 바뀌지 않는다. ko-KR 화면은 한국어가
  된다.

버린 대안:
- (A) 현 상태: 두 제품이 각각 막히거나 스크립트를 고쳤다.
- (C) "행동·상태 문구"만 정규식으로 고르는 제품 정책: 한국어 문장 목록에
  기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 제품 특화다.
ESLint 설정은 제품이 자기 규칙으로 덮어쓸 수 있는 자리다(한 locale 제품,
고유명사 허용).

위험·한계:
- 식 안에서 만든 문구는 보지 못한다. template literal, 삼항식, 객체
  prop(`heading.title` 같은 것)이 그렇다. 샘플의 이런 문구는 손으로
  옮겼고, `reference-page.test.tsx`가 ko-KR main 영역을 catalog·데이터
  밖 라틴 문자로 검사해 그 빈 곳을 샘플에서만 막는다.
- 고유명사·브랜드 이름도 걸린다. 제품이 선택자를 덮어쓰거나 그 줄에
  `eslint-disable-next-line`을 쓴다.
- ko-KR route 제목(`route.REFERENCE_RESOURCE_*`)은 catalog 안의 영어라
  그대로 뒀다(라우트 제목 정리는 0929/08-06 몫).
- `tests/e2e/reference-form.spec.ts`의 ko-KR 목록 h1 기대값을 "참조
  기능"으로 바꿨다. e2e는 이 worktree에서 돌리지 않았다(webServer가
  pnpm build를 부른다).
- 시각 골든(`tests/visual`)은 /examples/ui·states·platform만 찍는다.
  샘플 화면과 nav 문구는 바뀌지 않아 골든 영향이 없다고 본다(미실행).

검증:
- RED(수정 전):
  - E1 한글 주석 변이: `node scripts/check-i18n.ts` -> "hardcoded common
    user-facing locale literal in .../reference-resource-status-page.tsx",
    exit 1
  - E1b 영어 JSX 문구 변이: `check-i18n.ts` PASS exit 0, `eslint` exit 0
  - `check-i18n.ts --fixture` -> "I18n fixture was not rejected:
    english-accessible-name.tsx, english-jsx-text.tsx", exit 2
  - 새 ko-KR main 테스트: "limit 5 · tags ..." 가 남아 실패
- GREEN(수정 후):
  - E1 변이: `check-i18n.ts` PASS, `eslint` exit 0
  - E1b 변이: `eslint` -> 42:13 no-restricted-syntax, exit 1
  - `check-i18n.ts` PASS(224 keys), `--fixture` -> forbidden 7개 모두
    거절, "I18n contract failed:", exit 1. allowed에 영어 문구를 넣으면
    "I18n allowed fixture was rejected", exit 2
  - ko-KR main 테스트 통과
- `npx eslint src scripts tests recipes .storybook ... --max-warnings=0`
  통과, app·test·node 타입 검사 통과
- vitest: tests/unit + tests/component 209 files 2725 tests,
  tests/features 등 25 files 141 tests 통과
- `check-registries.ts` PASS, `check-ci-contract.ts` PASS,
  `verify-documentation-readiness.ts` PASS_SCOPED

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-02, 4.3
This commit is contained in:
DongHyeonka
2026-11-03 00:54:18 +09:00
parent ff33d58e95
commit 855d22ac1b
13 changed files with 225 additions and 34 deletions
@@ -68,13 +68,21 @@ route/form/failure 의미 값
## 검증
- `check:i18n`은 catalog key와 placeholder parity, 화면 코드의 한국어 literal,
backend message JSX 렌더링과 raw HTML 사용을 검사한다. 검사 범위는 공통 UI
디렉터리, `src/presentation/pages`, 모든 `src/features/*/presentation`이다.
컴포넌트 갤러리 `src/presentation/examples`는 일부러 뺐다
(`scripts/check-i18n.ts`의 `commonDirectories`, `featurePresentationDirectories`).
- `check:i18n:fixture`는 같은 탐색 규칙을 `tests/fixtures/i18n/forbidden` 트리에
돌린다. fixture 파일 하나라도 거절되지 않으면 종료 코드 2로 실패한다.
- `check:i18n`은 catalog key와 placeholder parity, backend message JSX 렌더링을
검사한다. 검사 범위는 공통 UI 디렉터리, `src/presentation/pages`, 모든
`src/features/*/presentation`이다. 컴포넌트 갤러리 `src/presentation/examples`는
일부러 뺐다(`scripts/check-i18n.ts`의 `commonDirectories`,
`featurePresentationDirectories`).
- 화면 문구가 catalog에서 오는지는 ESLint `no-restricted-syntax`가 본다
(`eslint.config.ts`의 `screenTextSelectors`, 0929/08-02). 대상은 글자가 든
`JSXText`와 표시·접근성 속성(`aria-label`, `title`, `placeholder`, `alt`,
`label` 등)의 문자열 literal이다. 주석은 AST에 없어 걸리지 않는다. 범위는 위와
같고 stories는 뺐다. 제품은 이 선택자를 자기 설정으로 덮어쓸 수 있다.
raw HTML은 FE-OC-019 ESLint 규칙이 거절한다.
- `check:i18n:fixture`는 같은 탐색 규칙과 위 ESLint 규칙을
`tests/fixtures/i18n/forbidden` 트리에 돌린다. fixture 파일 하나라도 거절되지
않으면 종료 코드 2로 실패한다. `tests/fixtures/i18n/allowed` 트리(한국어 주석,
구두점, catalog 문구)가 거절돼도 종료 코드 2로 실패한다.
- `tests/unit/i18n-contract.test.ts`는 `ERROR_REGISTRY`의 모든 `userMessageKey`가
ko-KR·en-US catalog에 있는지 확인한다.
- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
+59
View File
@@ -451,6 +451,49 @@ const hookRules = {
"react-hooks/exhaustive-deps": "error",
};
// 0929/08-02. Screen code takes its words from the message catalog. Comments
// are not in the AST, so only rendered text and accessible names are checked:
// JSX text and the display/accessibility attributes below that hold a letter
// in any script. Punctuation and numbers pass. Text built in an expression (a
// template literal, a ternary, an object prop such as `heading.title`) is not
// seen; review catches those. A product replaces these selectors in its own
// config, for example to allow a brand name or to drop the rule for a
// one-locale product. The component gallery (src/presentation/examples) and
// stories are workshop code and stay out; tests are outside these folders.
const screenTextDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
"src/presentation/design-system",
"src/presentation/forms",
"src/presentation/layouts",
"src/presentation/pages",
"src/presentation/routes",
"src/presentation/templates",
"src/features/*/presentation",
];
const screenTextAttributes =
"/^(?:aria-label|aria-description|aria-roledescription|aria-valuetext|aria-placeholder|title|placeholder|alt|label)$/";
const screenTextMessage =
"Screen words come from the message catalog: use message(key) (0929/08-02).";
const screenTextSelectors = [
{
selector: "JSXText[value=/\\p{L}/u]",
message: screenTextMessage,
},
{
selector: `JSXElement > JSXExpressionContainer > Literal[value=/\\p{L}/u]`,
message: screenTextMessage,
},
{
selector: `JSXAttribute[name.name=${screenTextAttributes}] > Literal[value=/\\p{L}/u]`,
message: screenTextMessage,
},
{
selector: `JSXAttribute[name.name=${screenTextAttributes}] > JSXExpressionContainer > Literal[value=/\\p{L}/u]`,
message: screenTextMessage,
},
];
export default [
{
ignores: [
@@ -860,6 +903,22 @@ export default [
],
},
},
{
// The same folders inside an i18n fixture tree, so check:i18n:fixture
// runs this rule on its fixtures. This entry replaces the general
// no-restricted-syntax list, so it carries the FE-OC-019 selectors too.
files: screenTextDirectories.flatMap((directory) => [
`${directory}/**/*.tsx`,
`tests/fixtures/i18n/*/${directory}/**/*.tsx`,
]),
ignores: ["**/*.stories.tsx"],
rules: {
"no-restricted-syntax": [
...commonSecurityRules["no-restricted-syntax"],
...screenTextSelectors,
],
},
},
{
files: [`tests/**/*.${sourceExtensions}`],
languageOptions: {
+50 -15
View File
@@ -9,7 +9,6 @@ import { EN_MESSAGES, KO_MESSAGES, MESSAGE_CATALOGS } from "../src/presentation/
const fixtureMode = process.argv.includes("--fixture");
const failures: string[] = [];
const sourceExtensions = /\.(?:ts|tsx|mts|cts)$/;
const koreanLiteral = /[가-힣]/;
const rawFailureRender =
/(?<!\$)\{\s*(?:failure|error|response|backend)(?:\?\.|\.)[\w?.]*message\s*\}/;
@@ -52,10 +51,19 @@ if (!fixtureMode) {
}
}
// 08-04. Screen code under these directories must take its words from the
// catalog. `src/presentation/examples` is the component gallery and stays out
// of scope on purpose. Fixture mode runs the same discovery on a fixture tree.
const sourceRoot = fixtureMode ? "tests/fixtures/i18n/forbidden" : ".";
// 0929/08-02. Whether screen code takes its words from the catalog is an
// ESLint rule now (eslint.config.ts, screenTextSelectors): this script looked
// for Hangul anywhere in a file, so it rejected Korean comments and let English
// copy through. Raw HTML is the FE-OC-019 ESLint rule. What stays here is
// catalog parity and rendering a backend message, which a selector cannot tell
// from an ordinary `.message` read. Fixture mode runs the ESLint rule on the
// fixture trees too, so this one gate shows the whole i18n contract rejecting
// every forbidden file and passing the allowed one.
// `src/presentation/examples` is the component gallery and stays out of scope
// on purpose.
const forbiddenFixtureRoot = "tests/fixtures/i18n/forbidden";
const allowedFixtureRoot = "tests/fixtures/i18n/allowed";
const sourceRoot = fixtureMode ? forbiddenFixtureRoot : ".";
const commonDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
@@ -92,19 +100,39 @@ const sources = (
await Promise.all(sourceDirectories.map(existingSourceFiles))
).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}`);
async function rawFailureRenders(files: readonly string[]): Promise<string[]> {
const found: string[] = [];
for (const file of files) {
if (rawFailureRender.test(await readFile(file, "utf8"))) {
found.push(`raw backend/error message rendered in ${file}`);
}
}
return found;
}
/** ESLint errors in a fixture tree, one entry per error, ending in the file. */
async function lintErrors(root: string): Promise<string[]> {
const { ESLint } = await import("eslint");
const results = await new ESLint({ ignore: false }).lintFiles([root]);
return results.flatMap((result) =>
result.messages
.filter((message) => message.severity === 2)
.map(
(message) =>
`${message.ruleId ?? "eslint"} ${message.line}:${message.column} ${message.message} in ${path.relative(process.cwd(), result.filePath)}`,
),
);
}
failures.push(...(await rawFailureRenders(sources)));
if (fixtureMode) failures.push(...(await lintErrors(forbiddenFixtureRoot)));
const allowedFixtureFailures = fixtureMode
? [
...(await rawFailureRenders(await listSourceFiles(allowedFixtureRoot))),
...(await lintErrors(allowedFixtureRoot)),
]
: [];
const report = i18nReportArtifactSchema.parse({
schemaVersion: 1,
mode: fixtureMode ? "negative-fixture" : "source",
@@ -135,6 +163,13 @@ if (fixtureMode && (fixtureFiles.length === 0 || unrejectedFixtures.length > 0))
);
process.exit(2);
}
// A comment, punctuation or catalog words must not be rejected (0929/08-02).
if (allowedFixtureFailures.length > 0) {
process.stderr.write(
`I18n allowed fixture was rejected:\n${allowedFixtureFailures.join("\n")}\n`,
);
process.exit(2);
}
if (failures.length > 0) {
process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
@@ -14,7 +14,12 @@ export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
"reference.list.create": "새 항목 만들기",
"reference.list.refresh": "새로고침",
"reference.list.resultCount": "총 {count}개 항목",
"reference.list.title": "참조 기능",
"reference.list.filterLimit": "최대 {limit}개",
"reference.list.filterTags": "태그 {tags}",
"reference.list.resources": "참조 리소스 목록",
"reference.form.back": "목록으로 돌아가기",
"reference.form.eyebrow": "폼 페이지",
"reference.form.title": "Reference resource 만들기",
"reference.form.description":
"presentation schema, command mapper, 422/conflict와 dirty navigation 정책을 실행합니다.",
@@ -33,12 +38,17 @@ export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
"reference.form.conflict": "충돌을 해결한 뒤 다시 제출할 수 있습니다.",
"reference.form.privacy":
"form value는 URL, storage, telemetry에 저장되지 않고 submit 시에만 application command로 변환됩니다.",
"reference.detail.eyebrow": "상세 페이지",
"reference.detail.titlePending": "참조 상세",
"reference.detail.resourceId": "리소스 ID",
"reference.detail.createdAt": "생성 시각",
"reference.detail.description":
"route param과 detail query의 reset 경계를 확인합니다.",
"reference.detail.summaryPending": "요약 정보를 준비하고 있습니다.",
"reference.detail.sectionSlot":
"이 영역에는 제품별 상세 section을 조립할 수 있습니다.",
"reference.detail.aside": "상세 페이지의 관련 정보 slot입니다.",
"reference.status.eyebrow": "상태 페이지 · 점검",
"reference.status.title": "잠시 사용할 수 없습니다.",
"reference.status.description":
"도메인 데이터나 raw 오류를 노출하지 않는 중립적인 상태 페이지 예시입니다.",
@@ -59,7 +69,12 @@ export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
"reference.list.create": "Create item",
"reference.list.refresh": "Refresh",
"reference.list.resultCount": "Total items: {count}",
"reference.list.title": "Reference feature",
"reference.list.filterLimit": "limit {limit}",
"reference.list.filterTags": "tags {tags}",
"reference.list.resources": "Reference resources",
"reference.form.back": "Back to the list",
"reference.form.eyebrow": "FormPage",
"reference.form.title": "Create a reference resource",
"reference.form.description":
"Runs the presentation schema, command mapper, 422/conflict and dirty navigation policies.",
@@ -78,12 +93,17 @@ export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
"reference.form.conflict": "Resolve the conflict, then submit again.",
"reference.form.privacy":
"Form values are never written to the URL, storage or telemetry; they become an application command only on submit.",
"reference.detail.eyebrow": "DetailPage",
"reference.detail.titlePending": "Reference detail",
"reference.detail.resourceId": "Resource ID",
"reference.detail.createdAt": "Created",
"reference.detail.description":
"Checks the reset boundary between the route parameter and the detail query.",
"reference.detail.summaryPending": "Preparing the summary.",
"reference.detail.sectionSlot":
"Product-specific detail sections can be assembled here.",
"reference.detail.aside": "Related information slot of the detail page.",
"reference.status.eyebrow": "StatusPage · maintenance",
"reference.status.title": "Temporarily unavailable.",
"reference.status.description":
"An example of a neutral status page that exposes no domain data or raw errors.",
@@ -21,19 +21,21 @@ export default function ReferenceResourceDetailPage() {
<DetailPage
key={resourceId}
breadcrumb={
<Link to="/examples/reference-resources">Reference resources</Link>
<Link to="/examples/reference-resources">
{message("reference.list.resources")}
</Link>
}
heading={{
eyebrow: "DetailPage",
title: resource?.title ?? "Reference detail",
eyebrow: message("reference.detail.eyebrow"),
title: resource?.title ?? message("reference.detail.titlePending"),
description: message("reference.detail.description"),
}}
metadata={
resource ? (
<dl>
<dt>Resource ID</dt>
<dt>{message("reference.detail.resourceId")}</dt>
<dd>{resource.resourceId}</dd>
<dt>Created</dt>
<dt>{message("reference.detail.createdAt")}</dt>
<dd>
{resource.createdAt
? date(new Date(resource.createdAt))
@@ -77,7 +77,7 @@ export default function ReferenceResourceFormPage() {
</button>
}
heading={{
eyebrow: "FormPage",
eyebrow: message("reference.form.eyebrow"),
title: message("reference.form.title"),
description: message("reference.form.description"),
}}
@@ -19,7 +19,7 @@ export default function ReferenceResourcePage() {
<CollectionPage
heading={{
eyebrow: message("reference.list.eyebrow"),
title: "Reference feature",
title: message("reference.list.title"),
description: message("reference.list.description"),
}}
actions={[
@@ -31,8 +31,12 @@ export default function ReferenceResourcePage() {
]}
activeFilters={
<p data-testid="reference-filter">
limit {filters.limit}
{filters.tags?.length ? ` · tags ${filters.tags.join(", ")}` : ""}
{message("reference.list.filterLimit", { limit: filters.limit })}
{filters.tags?.length
? ` · ${message("reference.list.filterTags", {
tags: filters.tags.join(", "),
})}`
: ""}
</p>
}
toolbar={
@@ -55,7 +59,7 @@ export default function ReferenceResourcePage() {
onAction={failureAction}
onRetry={query.retry}
>
<ul aria-label="Reference resources">
<ul aria-label={message("reference.list.resources")}>
{(query.data ?? []).map((resource) => (
<li key={resource.resourceId}>
<Link
@@ -24,7 +24,7 @@ export default function ReferenceResourceStatusPage() {
<StatusPage
variant="maintenance"
heading={{
eyebrow: "StatusPage · maintenance",
eyebrow: message("reference.status.eyebrow"),
title: message("reference.status.title"),
description: message("reference.status.description"),
}}
+1 -1
View File
@@ -118,7 +118,7 @@ for (const [state, payload, visible] of [
page,
}) => {
await page.route(LIST_API, (route) => route.fulfill({ json: payload }));
await signInAt(page, LIST_PATH, "Reference feature");
await signInAt(page, LIST_PATH, "참조 기능");
await expect(page.getByRole("main")).toContainText(visible);
await expectNoBlockingViolations(page);
});
@@ -31,6 +31,7 @@ import { createServerStateScopeRuntime } from "../../../src/adapters/query-cache
import { ApplicationProvider } from "../../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../../src/presentation/routes/app-router.tsx";
import { KO_MESSAGES } from "../../../src/presentation/i18n/catalog.ts";
import { createTestApplication } from "../../helpers/create-test-application.ts";
function renderReference(
@@ -121,7 +122,53 @@ function inputWith(
};
}
/**
* 0929/08-02. The main area's text and accessible names with every ko-KR
* catalog value and every given data value cut out. The lint rule sees JSX
* text and attributes only; this also sees words passed through props.
*/
function mainTextOutsideCatalog(data: readonly string[]): string {
const main = screen.getByRole("main");
const names = [...main.querySelectorAll("[aria-label],[title],[placeholder],[alt]")]
.flatMap((element) =>
["aria-label", "title", "placeholder", "alt"].map(
(name) => element.getAttribute(name) ?? "",
),
);
return [...data, ...Object.values(KO_MESSAGES)]
.sort((left, right) => right.length - left.length)
.reduce(
(text, known) => text.split(known).join(" "),
[main.textContent ?? "", ...names].join(" "),
);
}
describe("reference feature page states", () => {
it("shows no Latin words outside the catalog on the ko-KR screens", async () => {
const resource = {
resourceId: "reference-1",
title: "Loaded",
createdAt: null,
};
const input = inputWith({
listResources: async () => ({ ok: true, value: [resource] }),
});
for (const [url, ready] of [
["/examples/reference-resources?limit=5&tags=open", "Loaded"],
["/examples/reference-resources/items/reference-1", "Detail"],
["/examples/reference-resources/new", "저장"],
["/examples/reference-resources/status", "목록으로 이동"],
] as const) {
const view = renderReference(input, url);
await screen.findAllByText(ready);
expect(
mainTextOutsideCatalog(["reference-1", "Loaded", "Detail", "open"]),
url,
).not.toMatch(/[A-Za-z]/);
view.unmount();
}
});
it("mounts list and detail keys under the installed governed namespace", async () => {
expect(REFERENCE_RESOURCE_QUERY_NAMESPACE).toEqual({
namespaceId: "reference-resource",
@@ -0,0 +1,10 @@
// 한국어 주석은 화면 문구가 아니다. 문구는 catalog에서 온다.
export function CatalogAction({
message,
}: Readonly<{ message: (key: "action.retry") => string }>) {
return (
<button type="button" aria-label={message("action.retry")}>
{message("action.retry")} ·
</button>
);
}
@@ -0,0 +1,3 @@
export function EnglishAccessibleName() {
return <ul aria-label="Reference resources" />;
}
@@ -0,0 +1,3 @@
export function EnglishHeading() {
return <h1>Reference feature</h1>;
}