fix(i18n): 상태 화면 문구를 최종 사용자 말로 쓰고 숫자·단수형·문장 조립을 catalog에 맡긴다

화면 문구 셋이 어긋난다.
- 상태 화면 문구가 템플릿 개발자용이다(04-01). 생성 기능은 모두
  `session-required`라 로그인 전 최종 사용자에게 "이 화면은 인증 연동 지점을
  확인하기 위한 보호 라우트입니다."가 보인다. 끈 기능 화면은 "코드에는
  포함되어 있으며 운영자가 다시 켤 수 있습니다.", 연동 실패 화면은 "외부 인증
  소유자가 연결되면…"이다.
- 숫자를 locale formatter 없이 그린다(04-03). 생성 목록이 "총 12345개 항목"을
  그리고, TextArea는 en에서 남은 1자도 "1 characters remaining"이다.
- ko·en 뜻이 다르다(04-07). en `form.conflict`에 "최신 상태를 확인해 주세요"가
  없고, en 문서 제목 "Page not found"와 h1 "Page not found."가 다르다.
  ErrorSummary가 번역 문장 사이에 JSX 글자 ": "를 넣는다.

고른 방법: 세 설명을 사용자 말("이 화면을 보려면 로그인해 주세요." 등)로 바꾸고
운영 설명은 뺐다. 생성 목록은 `useLocale().number(total)`을 넘긴다. TextArea는
`plural`로 `form.remaining.one`(en 단수)과 `form.remaining`을 고른다. en 충돌
문구에 행동을 더하고 not-found 제목을 h1과 같게 했다. 오류 요약 항목은
`form.errorSummary.item` "{label}: {message}"로 잇는다. 연동 실패 화면의 제목
"로그인 연동이 필요합니다."는 짝 백엔드 매뉴얼이 그 글자로 가리켜 그대로 뒀다.
검증 V4가 반박한 부분(세 화면에 행동 버튼이 없다, ProgressBar `%`)은 고치지
않았다: 셸 탐색이 늘 있고, `%`는 ko·en 결과가 같다.

위험·한계: 다운스트림이 이 키의 옛 문장을 시험으로 고정했으면 문장을 바꾼다.
이미 생성한 기능의 목록 페이지는 `count: query.data.total`을 그대로 갖는다.
`number(query.data.total)`로 바꾸면 된다(생성 명령의 새 출력과 같다).

검증: `tests/unit/i18n-contract.test.ts`(개발자 낱말, not-found 제목, 항목
문장), `tests/component/design-system-a11y.test.tsx`(en 단수·복수),
`tests/unit/create-feature.test.ts`(생성 목록의 `number(`)가 고치기 전에
실패하고 고친 뒤 통과한다. 생성 기능 시험의 total 12345 → "총 12,345개 항목"은
FE-GATE-005가 돌린다(desktop, PR 본문).

Refs: 1112/04-01, 1112/04-03, 1112/04-07
This commit is contained in:
DongHyeonka
2026-11-13 19:03:18 +09:00
parent 8bcecabc40
commit d42ad073ee
9 changed files with 90 additions and 19 deletions
+7 -4
View File
@@ -1182,7 +1182,7 @@ ${write ? `import { ${camel}RouteUrl } from "./${base}-routes.ts";\n` : ""}impor
* the page heading.
*/
export default function ${pascal}ListPage() {
const { message } = useLocale();
const { message, number } = useLocale();
const query = use${pascal}Items();
return (
<CollectionPage
@@ -1203,7 +1203,9 @@ export default function ${pascal}ListPage() {
: ""
}
resultCount={
query.data ? message("${camel}.list.resultCount", { count: query.data.total }) : null
query.data
? message("${camel}.list.resultCount", { count: number(query.data.total) })
: null
}
>
<AsyncSurface state={query.state} onRetry={query.retry}>
@@ -1348,13 +1350,14 @@ describe("${names.id} list page through the router", () => {
HttpResponse.json({
success: true,
data: [{ id: "item-1", name: "First item" }],
meta: { page: { number: 0, size: 20, total: 41, sort: null } },
meta: { page: { number: 0, size: 20, total: 12345, sort: null } },
}),
),
);
await openList();
expect(await screen.findByText("총 41개 항목")).toBeVisible();
// 1112/04-03. The count is a locale-formatted number.
expect(await screen.findByText("총 12,345개 항목")).toBeVisible();
});
// The backend answers an empty list as \`data: []\`, never by dropping \`data\`.
@@ -27,7 +27,7 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
},
ref,
) {
const { message } = useLocale();
const { message, plural } = useLocale();
const [uncontrolledValue, setUncontrolledValue] = useState(
String(defaultValue ?? ""),
);
@@ -55,7 +55,10 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
? null
: maxLengthMessage
? maxLengthMessage(remaining)
: message("form.remaining", { count: remaining });
: plural(remaining, {
one: message("form.remaining.one", { count: remaining }),
other: message("form.remaining", { count: remaining }),
});
return (
<>
<textarea
+5 -2
View File
@@ -65,7 +65,7 @@ export function ErrorSummary<Values extends FormValues>(props: Readonly<{
<Heading id={headingId}>{message("form.errorSummary")}</Heading>
{entries.length > 0 ? (
<ul>
{entries.map(([name, message]) => (
{entries.map(([name, error]) => (
<li key={name}>
<a
href={`#${fieldId(name)}`}
@@ -75,7 +75,10 @@ export function ErrorSummary<Values extends FormValues>(props: Readonly<{
onFocusField(name);
}}
>
{fieldLabels[name]}: {message}
{message("form.errorSummary.item", {
label: fieldLabels[name],
message: error,
})}
</a>
</li>
))}
+12 -8
View File
@@ -76,17 +76,17 @@ const PLATFORM_KO_MESSAGES = {
"route.invalid.action": "안전한 탐색 링크를 사용해 주세요.",
"route.disabledFeature.title": "현재 사용할 수 없는 기능입니다.",
"route.disabledFeature.description":
"이 기능은 배포 설정에서 중지되어 있습니다. 코드에는 포함되어 있으며 운영자가 다시 켤 수 있습니다.",
"지금은 이 기능을 쓸 수 없습니다. 다른 메뉴를 이용하거나 나중에 다시 확인해 주세요.",
"route.disabledFeature.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": "새 버전으로 한 번만 전환합니다.",
@@ -124,6 +124,7 @@ const PLATFORM_KO_MESSAGES = {
"template.dangerActions": "위험 작업",
"template.supportReference": "지원 참조: {reference}",
"form.errorSummary": "입력 내용을 확인해 주세요.",
"form.errorSummary.item": "{label}: {message}",
"form.unsaved.title": "저장하지 않은 변경이 있습니다.",
"form.unsaved.description": "이 화면을 떠나면 입력한 내용이 사라집니다.",
"form.validation.required": "필수 입력값입니다.",
@@ -157,6 +158,7 @@ const PLATFORM_KO_MESSAGES = {
"form.reauthLosesInput":
"다시 로그인하면 이 화면에 입력한 내용은 사라집니다. 필요하면 먼저 복사해 두세요.",
"form.remaining": "{count}자 남음",
"form.remaining.one": "{count}자 남음",
"toast.region": "알림",
"error.network_unreachable": "네트워크에 연결할 수 없습니다.",
"error.request_timeout": "요청 시간이 초과되었습니다.",
@@ -253,7 +255,7 @@ const PLATFORM_EN_MESSAGES = {
"route.EXAMPLES_PLATFORM.navigation": "Platform composition",
"route.EXAMPLES_PLATFORM.title": "Platform composition",
"route.NOT_FOUND.navigation": "Not found",
"route.NOT_FOUND.title": "Page 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.",
@@ -282,17 +284,17 @@ const PLATFORM_EN_MESSAGES = {
"route.invalid.action": "Use a safe navigation link.",
"route.disabledFeature.title": "This feature is not available right now.",
"route.disabledFeature.description":
"The deployment configuration has switched it off. It is still part of this build and an operator can switch it back on.",
"You cannot use this feature right now. Use another menu or check again later.",
"route.disabledFeature.action": "Use another 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.",
"You cannot sign in right now. Try again in a moment.",
"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.",
"Sign in to view this page.",
"route.documentTitle": "{title} · {appName}",
"chunk.checking": "Checking the new release information.",
"chunk.reloadOnce": "Switching to the new version once.",
@@ -329,6 +331,7 @@ const PLATFORM_EN_MESSAGES = {
"template.dangerActions": "Dangerous actions",
"template.supportReference": "Support reference: {reference}",
"form.errorSummary": "Review the entered information.",
"form.errorSummary.item": "{label}: {message}",
"form.unsaved.title": "You have unsaved changes.",
"form.unsaved.description":
"The entered information will be lost if you leave this page.",
@@ -357,12 +360,13 @@ const PLATFORM_EN_MESSAGES = {
"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.",
"Another update conflicts with this change. Your input has been preserved, so check the latest version.",
"form.resendLater":
"The request sent again was not processed. Send the same request again shortly.",
"form.reauthLosesInput":
"Signing in again clears what you entered on this page. Copy it first if you need it.",
"form.remaining": "{count} characters remaining",
"form.remaining.one": "{count} character remaining",
"toast.region": "Notifications",
"error.network_unreachable": "The network is unavailable.",
"error.request_timeout": "The request timed out.",
@@ -41,6 +41,7 @@ export type MessageParameters = Readonly<{
"route.documentTitle": { title: string; appName: string };
"template.supportReference": { reference: string };
"form.remaining": { count: number };
"form.remaining.one": { count: number };
"home.runtime.summary": { buildId: string; releaseId: string };
"boot.supportReference": { reference: string };
}>;
@@ -17,6 +17,7 @@ import {
Tooltip,
useToast,
} from "../../src/presentation/design-system/index.ts";
import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
/**
* 1112/05-10, 05-11, 05-13, 05-14, 05-17. What the shared primitives promise
@@ -267,4 +268,27 @@ describe("TextArea counter", () => {
expect(screen.queryByRole("status")).not.toBeInTheDocument();
expect(field).toHaveAccessibleDescription(/27/u);
});
// 1112/04-03. The count picks the locale's singular and plural forms.
it("uses the singular form for one character left in English", () => {
render(
<LocaleProvider initialLocale="en-US">
<TextArea label="Note" maxLength={5} defaultValue="abcd" />
</LocaleProvider>,
);
expect(screen.getByRole("textbox", { name: "Note" })).toHaveAccessibleDescription(
"1 character remaining",
);
});
it("keeps the plural form for other counts", () => {
render(
<LocaleProvider initialLocale="en-US">
<TextArea label="Note" maxLength={5} defaultValue="abc" />
</LocaleProvider>,
);
expect(screen.getByRole("textbox", { name: "Note" })).toHaveAccessibleDescription(
"2 characters remaining",
);
});
});
+1 -1
View File
@@ -121,7 +121,7 @@ describe("generic application router", () => {
await user.selectOptions(localeSelect, "en-US");
await waitFor(() =>
expect(document.title).toBe("Page not found · Frontend Skeleton"),
expect(document.title).toBe("Page not found. · Frontend Skeleton"),
);
expect(
screen.getByRole("heading", { name: "Page not found.", level: 1 }),
+3 -2
View File
@@ -179,7 +179,8 @@ describe("create:feature rendering", () => {
expect(contribution).toContain(`const API_PATH = "${apiPath}";`);
});
// 1103/03-02. A page list's meta.page.total counts every page.
// 1103/03-02. A page list's meta.page.total counts every page; 1112/04-03 shows
// it as a locale-formatted number.
it("shows the total the backend counted, not the length of the first page", () => {
const { files } = plan({ id: "invoice-feature" });
@@ -188,7 +189,7 @@ describe("create:feature rendering", () => {
);
expect(
files.get("src/features/invoice-feature/presentation/invoice-list-page.tsx"),
).toContain('message("invoice.list.resultCount", { count: query.data.total })');
).toContain('message("invoice.list.resultCount", { count: number(query.data.total) })');
});
});
+32
View File
@@ -130,3 +130,35 @@ describe("internationalization formatter contract", () => {
).toBe(FORMAT_FALLBACK);
});
});
// 1112/04-01, 04-07. Copy an end user reads on the platform status surfaces.
describe("platform status copy", () => {
const ENGLISH_AND_KOREAN = [KO_MESSAGES, EN_MESSAGES] as const;
it("does not explain the template to the end user on status surfaces", () => {
const developerWords =
/라우트|연동 지점|seam|코드에는 포함|운영자|operator|protected route|this build/iu;
for (const catalog of ENGLISH_AND_KOREAN) {
for (const key of [
"route.auth.required.description",
"route.auth.integration.description",
"route.disabledFeature.description",
] as const) {
expect(catalog[key], key).not.toMatch(developerWords);
}
}
});
it("titles the not-found document the same as its heading", () => {
for (const catalog of ENGLISH_AND_KOREAN) {
expect(catalog["route.NOT_FOUND.title"]).toBe(catalog["page.notFound.title"]);
}
});
it("joins an error summary entry through the catalog", () => {
expect(formatMessage("en-US", "form.errorSummary.item", {
label: "Name",
message: "Required.",
})).toBe("Name: Required.");
});
});