Files
clean-architecture-frontend…/docs/architecture
DongHyeonka ff33d58e95 feat(i18n): 문구 보간 파라미터를 catalog의 {이름}에서 만든다 (0929/08-03)
문제: 보간 파라미터 타입이 플랫폼 파일의 닫힌 목록 `MessageParameters`에만
있다. 목록에 없는 기능 키는 `[parameters?: never]`가 된다. 그래서
`formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를
통과하고 실행하면 대체 문구를 돌려주며, `{ count: 1 }`을 넣으면 TS2345로
거절된다. 샘플은 타입 없는 `resolveMessage`로 우회했고, tech-log는 템플릿
파일에 키 11개를 넣었다.

고른 방법: (B) catalog가 `as const`이므로 ko-KR 문자열 literal의
`{이름}`에서 `MessageArguments<Key>`를 만든다. 값 타입은
`string | number`다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로
덮어쓴다. 덮어쓰기는 catalog 파라미터와 교집합이라 좁히기만 한다. 덮어쓴
항목이 catalog 문자열과 어긋나도 catalog의 자리표시자는 계속 필수다.
`ParameterlessMessageKey`도 "자리표시자가 없는 키"로 같은 규칙에서
만든다. 기존 덮어쓰기 8개는 값 타입을 좁히므로 그대로 둔다.
새 개념이 없고, 기능이 템플릿 파일을 고치지 않는다.

버린 대안: (C) 기능 모듈이 파라미터 타입을 따로 선언하고 설치 조립이
교집합을 만든다. 값 타입을 정확히 쓸 수 있지만 catalog와 선언을 따로
맞춰야 한다.

위험·한계:
- 값 타입이 `string | number`로 넓다. 좁히려면 `MessageParameters`에
  덮어쓴다.
- 자리표시자는 ko-KR 문자열에서 읽는다. 다른 locale과의 일치는
  `tests/unit/i18n-contract.test.ts`의 parity 검사가 지킨다.
- ICU 복수형·select처럼 `{이름}`으로 표현하지 못하는 문구는 다루지
  않는다(VD-06 재검토 조건).
- 타입 검사 비용(`tsc -p tsconfig.app.json --extendedDiagnostics`):
  Types 287,440 -> 289,911(+0.9%), Instantiations 721,217 -> 748,663
  (+3.8%). 실행 시간은 load average 9~21에서 전·후 모두 1.0~2.6초로
  흔들려 차이를 구분할 수 없었다.
- 기능 키 검사(`tests/features/reference-feature/feature-module.test.ts`)는
  샘플과 함께 지워지도록 샘플 테스트 폴더에 두었다. 플랫폼 fixture는
  샘플 키에 기대지 않는다.

검증:
- RED: `npx tsc -p tsconfig.test.json --noEmit`
  feature-module.test.ts(23,5): error TS2578: Unused '@ts-expect-error'
  feature-module.test.ts(26,60): error TS2345: Argument of type
  '{ count: number; }' is not assignable to parameter of type 'undefined'.
- GREEN: 같은 명령 오류 0. app·node·recipes 타입 검사 통과.
- `check:types:fixture:i18n-params` fixture: 기존 3줄은 TS2554/TS2345로
  계속 실패하고, 더한 덮어쓰기 좁힘 줄은 TS2322로 실패한다.
- vitest: tests/features/reference-feature, i18n-contract,
  locale-platform 19 files 97 tests 통과.
- 샘플 목록 화면이 타입 있는 `message()`로 결과 수를 그린다.

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-03
2026-11-03 00:54:18 +09:00
..