@gaonjs/cli 0.64.0 → 0.65.2

package/dist/templates/project/agents/i18n.md.tpl

@@ -6,39 +6,49 @@
 
 ## 한 장 요약
 
+문구의 **소유자**가 파일 위치를 정한다 — 화면이면 **그 앱**, 화면 밖이면 **domain**.
+
 | 문구가 어디에 보이나 | 카탈로그 파일 | 부르는 곳 |
 |---|---|---|
-| **화면**(.vue 페이지·컴포넌트·레이아웃) | `locales/<로케일>/frontend.json`(앱 공용) · `apps/<앱>/locales/<로케일>.json`(그 앱 전용) | **`import { t } from 'gaonjs/vue'`** |
-| 메일·잡·크론·검증 문안·로그 등 **서버** | `locales/<로케일>/backend.json` | `import { t } from 'gaonjs/i18n'` |
+| **화면**(.vue 페이지·컴포넌트·레이아웃) | `apps/<앱>/locales/<로케일>/frontend.json` **(앱마다 필수)** | **`import { t } from 'gaonjs/vue'`** |
+| 그 앱 **컨트롤러**의 서버 문구(flash·리다이렉트 안내) | `apps/<앱>/locales/<로케일>/backend.json` (선택) | `import { t } from 'gaonjs/i18n'` |
+| 메일·잡·크론·검증 문안·로그 등 **도메인 공통** | `domain/locales/<로케일>/backend.json` | `import { t } from 'gaonjs/i18n'` |
 
-한 문장: **"화면에 보이는 문구는 frontend + 클라 `t()`, 화면 밖으로 나가는 문구는
+한 문장: **"화면에 보이는 문구는 그 앱의 frontend + 클라 `t()`, 화면 밖으로 나가는 문구는
 backend + 서버 `t()`."** 텍스트는 카탈로그에 **한 번만** 쓴다 — 컨트롤러가 키를 다시
 열거하거나 타입을 손으로 선언하지 않는다.
 
+**루트 공용 `locales/` 는 없다**(결정 459). 여러 앱이 함께 쓰는 UI 문구는 **각 앱에
+같은 키를 둔다**(§10) — doctor 가 전 앱 존재를 강제하므로 손으로 맞출 일은 없다.
+
 ## 정본 규칙
 
-### 1. 카탈로그 저작 레이아웃 (결정 454)
+### 1. 카탈로그 저작 레이아웃 (결정 459)
 
 ```
-locales/
-  ko/
-    backend.json      # 서버 전용 — 메일·잡·검증(validation.*)·알림. 클라로 나가지 않는다.
-    frontend.json     # 앱 공용 화면 문구 — nav·버튼·공통 라벨.
-  en/
-    backend.json
-    frontend.json
+domain/
+  locales/
+    ko/backend.json      # 도메인 공통 서버 전용 — 메일·잡·검증(validation.*)·알림.
+    en/backend.json      # 화면 문구(frontend.json)는 여기 둘 수 없다 — 부팅 에러.
 apps/
-  web/locales/ko.json     # web 앱 전용 화면 문구(web 번들에만 실린다)
-  admin/locales/ko.json   # admin 앱 전용 화면 문구(admin 번들에만 실린다)
+  web/
+    locales/
+      ko/frontend.json   # web 화면 문구 — web 번들 청크에만 실린다. (필수)
+      ko/backend.json    # web 컨트롤러 전용 서버 문구. (선택)
+      en/frontend.json
+  admin/
+    locales/ko/frontend.json …
 ```
 
-- **키 이름은 스코프와 무관하다** — `t('nav.home')` 은 파일이 어디에 있든 그대로다.
+- **키 이름은 위치와 무관하다** — `t('nav.home')` 은 파일이 어디에 있든 그대로다.
   파일 위치가 곧 "누가 이 문구를 볼 수 있나"를 정한다.
-- **backend 는 클라 번들에 물리적으로 없다** — 앱 카탈로그 청크의 입력이 frontend 뿐이라,
-  서버 문구가 `/assets/*` 로 새지 않는다. 타입 축도 같은 경계를 지켜 클라에서 backend 키를
-  참조하면 **컴파일 에러**다.
-- **한 키를 두 스코프에 두면 부팅 에러**(어느 번역이 나갈지가 병합 순서에 좌우되면 안 된다).
+- **backend 는 클라 번들에 물리적으로 없다** — 앱 카탈로그 청크의 입력이 그 앱
+  `frontend.json` **하나**뿐이라 서버 문구가 `/assets/*` 로 샐 길이 없다. 타입 축도 같은
+  경계를 지켜 클라에서 backend 키를 참조하면 **컴파일 에러**다.
+- **한 키를 두 스코프에 두면 부팅 에러** — 같은 앱의 frontend↔backend 도, 앱↔도메인도
+  마찬가지다(어느 번역이 나갈지가 병합 순서·요청 컨텍스트에 좌우되면 안 된다).
 - 카탈로그는 **순수 JSON**(주석·트레일링 콤마 금지). 로케일 등록 = 폴더 존재.
+- **위치는 관례로 고정**이라 `i18n.dir` 설정이 없다(결정 459 — 있으면 doctor 가 error).
 - `gaon.config.ts` 의 `i18n.fallbackLng` 가 **기준 로케일**이다(키 유니온의 출처 · 결정 352).
 
 ```ts
@@ -90,7 +100,15 @@ const layouts = import.meta.glob('./layouts/*.vue', { eager: true })
 void createGaonApp({ pages, layouts, routes, messages: { catalogs, fallbackLng } })
 ```
 
-### 3. 서버 문구 = 서버 `t()` (역할 유지)
+### 3. 서버 문구 = 서버 `t()` (결정 459 · 스코프 2개)
+
+서버 `t()` 의 해석 범위는 **호출이 일어난 컨텍스트**가 정한다:
+
+| 어디서 불렀나 | 보이는 카탈로그 | 우선순위 |
+|---|---|---|
+| `domain/**`(mails·jobs·services·listeners·schedule) | domain-backend **만** | — (단일) |
+| `apps/<앱>/**`(컨트롤러 등 서버 코드) | 그 앱 backend ∪ 그 앱 frontend ∪ domain-backend | **앱 먼저**, 없으면 domain |
+| 워커(`gaon work`)·크론·부팅 스크립트 | domain-backend **만**(앱 컨텍스트가 없다) | — (단일) |
 
 ```ts
 // domain/mails/welcome.ts — 수신자 로케일로 렌더된다(결정 160)
@@ -116,28 +134,47 @@ export const SendDigest = job(async ({ locale }: { locale: string }) => {
 
 | 표면 | 시그니처 | 쓰는 곳 |
 |---|---|---|
-| 번역 | `t(key, params?)` | 요청 로케일(ALS) 자동 추종 |
+| 번역 | `t(key, params?)` | 요청 로케일(ALS) + 앱 스코프 자동 추종 |
 | 현재 언어 | `currentLanguage(): string` | 요청 로케일 |
+| 현재 앱 스코프 | `currentApp(): string \| undefined` | 진단용(요청 밖이면 undefined) |
 | 지원 언어 | `languages(): readonly string[]` | 설정된 supportedLngs |
 | 로케일 고정 | `runWithLanguage(lng, fn)` | 잡·크론·스크립트(요청 밖) |
 | 고정 번역기 | `translator(lng)` | 테스트·비요청 경로 |
 
-서버 `t()` 는 backend ∪ frontend 를 **모두** 볼 수 있다(SSR·로그·관리 스크립트에서 화면
-문구가 필요할 수 있다). 반대 방향만 막힌다 — 클라는 frontend 만.
+앱 스코프에서는 서버 `t()` 가 그 앱의 backend ∪ frontend 를 **모두** 볼 수 있다(SSR·로그·
+관리 스크립트에서 화면 문구가 필요할 수 있다 · 결정 459 O5). 반대 방향만 막힌다 —
+클라는 frontend 만.
 
-### 4. 키·파라미터 타입 — `.gaon/messages.d.ts` 두 갈래 (결정 454)
+**⚠️ 도메인 코드는 앱 키에 기대면 안 된다.** 앱 요청이 부른 도메인 서비스는 같은 요청
+컨텍스트라 앱 네임스페이스가 **우연히 보인다**. 그런데 같은 코드가 워커·크론에서 불리면
+앱 스코프가 없어 그 키가 빈다 — "개발 중엔 되는데 잡에서만 키 문자열이 뜬다" 는 가장 나쁜
+형태다. `gaon doctor` 의 `i18n-server-scope` 가 정적으로 막는다(§9).
+
+### 4. 키·파라미터 타입 — `.gaon/messages.d.ts` 두 갈래 (결정 454 · 459)
 
 `gaon gen`/`dev`/`check` 가 카탈로그를 읽어 **두 유니온**을 생성한다:
-서버(`gaonjs/i18n`) = backend ∪ frontend / 클라(`gaonjs/vue`) = frontend 만.
-
-```ts fragment expect-error
-t('posts.heading')                    // ✅
-t('mail.welcome.subject', { name })   // ❌ 클라에서 backend 키 — 컴파일 에러
-t('greeting')                         // ❌ {{name}} 보간 파라미터 누락 — 컴파일 에러
-t('greeting', { nam: '가온' })        // ❌ 파라미터 이름 오타 — 컴파일 에러
-t('cart.items', { count: 'many' })    // ❌ count 는 number — 컴파일 에러
+서버(`gaonjs/i18n`) = domain-backend ∪ 전 앱 backend ∪ 전 앱 frontend /
+클라(`gaonjs/vue`) = 전 앱 frontend 만.
+
+```vue expect-error
+<!-- apps/web/pages/Posts/Bad.vue — 아래 세 줄은 **전부 컴파일 에러**다 -->
+<script setup lang="ts">
+import { t } from 'gaonjs/vue'
+const a = t('mail.welcome.subject', { name: '가온' })  // ❌ 클라에서 backend 키
+const b = t('greeting')                                // ❌ {{name}} 보간 파라미터 누락
+const c = t('greeting', { nam: '가온' })               // ❌ 파라미터 이름 오타
+</script>
 ```
 
+**유니온은 앱별로 못 나눈다** — 두 앱이 `GaonMessages.keys` 를 서로 다른 유니온으로
+augment 하면 **TS2717**(Subsequent property declarations must have the same type)이고,
+`gaon check` 는 단일 tsc 프로그램이라 앱마다 다른 프로그램을 돌릴 수 없다(결정 454 실측 ·
+결정 459 §5.1 로 유효). **파일은 앱별인데 타입은 프로젝트 전역**인 이 비대칭이 함정이다 —
+그래서 앱 경계는 ① 번들 물리 경계 ② doctor 가 강제한다(§9).
+
+산출은 **루트 `.gaon/messages.d.ts` 하나**다(앱별로 쪼개면 "앱별 타입" 이라는 오해를
+만든다 · 결정 459 O7). 앱별 `.gaon/` 에는 **값 모듈**(`messages.catalog.ts`)만 나간다.
+
 카탈로그가 없거나 frontend 스코프가 없으면 키가 `string` 으로 열린다(무회귀). 이 파일은
 자동 생성이니 직접 수정하지 않는다.
 
@@ -148,11 +185,11 @@ t('cart.items', { count: 'many' })    // ❌ count 는 number — 컴파일 에
 **같은 문자열**을 낸다(85 케이스 동치 게이트로 고정).
 
 ```json
-// locales/en/frontend.json — 영어는 단수/복수 구분
+// apps/web/locales/en/frontend.json — 영어는 단수/복수 구분
 { "cart": { "items_one": "{{count}} item", "items_other": "{{count}} items" } }
 ```
 ```json
-// locales/ko/frontend.json — 한국어는 _other 만
+// apps/web/locales/ko/frontend.json — 한국어는 _other 만
 { "cart": { "items_other": "상품 {{count}}개" } }
 ```
 
@@ -202,27 +239,49 @@ t(key as never)                        // 없으면 'posts.abc' 가 화면에
   녹는다(이 계약이 막는 것이 정확히 그 침묵이다).
 - 런타임까지 **실패로 만들고 싶다면**(엄격 모드) 지금은 지원하지 않는다 — 필요하면 요청하라.
 
-### 9. 로케일 커버리지 — `locale-parity` 경고 (결정 216)
+### 9. 정적 검사 3종 (`gaon doctor`)
+
+| 검사 | 무엇을 잡나 | 등급 |
+|---|---|---|
+| `locale-parity` | 같은 스코프 안에서 **로케일 간** 키 부분 누락(§9.1) | 경고 |
+| `i18n-app-scope` | 클라 `t()` 가 **그 앱에 없는** 키 참조 · shared 키가 일부 앱에만 존재 | 오류 |
+| `i18n-server-scope` | 서버 `t()` 가 **소유자 경계**를 넘는 키 참조(도메인 → 앱 키 등) | 오류 |
+
+#### 9.1 로케일 커버리지 — `locale-parity` (결정 216 · 456 · 459)
 
 키 유니온은 기준 로케일 하나에서 나오므로, 어떤 키를 `ko` 에만 넣고 `ja` 에 빠뜨리면
-컴파일은 통과하고 일본어 사용자만 조용히 fallback 을 본다. `gaon doctor` 의 `locale-parity`
-가 **스코프별로**(backend↔backend · frontend↔frontend) 키 diff 를 계산해 경고한다.
+컴파일은 통과하고 일본어 사용자만 조용히 fallback(서버) 또는 키 문자열(클라)을 본다.
+비교 단위는 **3종**이다: ① domain-backend ② 앱별 frontend ③ 앱별 backend.
+**스코프·소유자를 가로지르는 비교는 하지 않는다** — 앱 전용 키가 전량 "도메인에 없음"
+으로 뜨는 오탐이 되기 때문이다. 복수형 접미사는 base 로 정규화해 비교한다(en `_one`/`_other`
+와 ko `_other` 의 정당한 차이를 누락으로 세지 않는다).
+
+### 10. 여러 앱이 함께 쓰는 문구 · `shared/` 컴포넌트 (결정 459 O1)
 
-**앱 스코프 카탈로그도 대상이다**(결정 456) — `apps/<앱>/locales/<로케일>.json` 은 그 앱
-안에서만 비교한다(스코프 이름 `app:<앱>`). 앱 전용 키는 루트에 없는 것이 정상이라
-루트와 교차 비교하지 않는다. 앱 카탈로그의 누락은 fallback 이 아니라 **키 문자열이 그대로
-화면에 뜬다**(결정 455) — 그래서 정적으로 먼저 잡는다.
+공용 카탈로그가 없으므로, 여러 앱이 쓰는 UI 원자 문구(`ui.close`·`ui.prev`·`ui.save` …)는
+**각 앱의 `frontend.json` 에 같은 키를 둔다**. 복제가 비용처럼 보이지만 대안이 더 나쁘다 —
+문구를 props 로 끌어올리면(`closeLabel`·`prevLabel`) 원자 컴포넌트마다 prop 이 생기고
+사용처마다 문구를 다시 적어야 해서, 결정 454 가 없앤 "선언 지점 3곳" 통증이 되살아난다.
+
+**`shared/` 컴포넌트가 쓰는 키는 모든 앱에 있어야 한다** — shared 는 어느 앱 번들에도
+실릴 수 있어서, 키가 한 앱에만 있으면 **다른 앱 화면에서만** 키 문자열이 뜨는 조용한
+실패가 된다. `i18n-app-scope` 가 누락된 앱 이름을 짚어 준다:
+
+```
+shared 컴포넌트가 쓰는 'ui.close' 가 일부 앱 카탈로그에 없습니다(누락: admin)
+→ apps/admin/locales/<로케일>/frontend.json 에 같은 키를 추가하고 gaon gen
+```
 
 ## 정본 예시
 
-### (a) 새 화면 문구 추가 — 앱 전용
+### (a) 새 화면 문구 추가 — 그 앱 전용
 
-```jsonc
-// apps/web/locales/ko.json
+```json
+// apps/web/locales/ko/frontend.json
 { "posts": { "heading": "게시글 목록", "empty": "아직 글이 없습니다." } }
 ```
-```jsonc
-// apps/web/locales/en.json  ← 같은 키를 나란히(locale-parity)
+```json
+// apps/web/locales/en/frontend.json  ← 같은 키를 나란히(locale-parity)
 { "posts": { "heading": "Posts", "empty": "No posts yet." } }
 ```
 ```vue fragment
@@ -235,10 +294,14 @@ import { t } from 'gaonjs/vue'
 gaon gen   # .gaon/messages.d.ts(두 갈래) + apps/web/.gaon/messages.catalog.ts 재생성
 ```
 
-### (b) 앱 공용 chrome 문구(모든 앱이 쓰는 nav)
+### (b) 여러 앱이 쓰는 chrome 문구 — 각 앱에 복제
 
-```jsonc
-// locales/ko/frontend.json
+```json
+// apps/web/locales/ko/frontend.json
+{ "nav": { "home": "홈", "posts": "게시판" } }
+```
+```json
+// apps/admin/locales/ko/frontend.json  ← 같은 키를 admin 에도(전 앱 존재를 doctor 가 강제)
 { "nav": { "home": "홈", "posts": "게시판" } }
 ```
 ```vue
@@ -254,33 +317,64 @@ import { t, Link } from 'gaonjs/vue'
 </template>
 ```
 
-### (c) 서버 전용 문구(메일)
+### (c) 도메인 공통 서버 문구(메일·검증)
 
-```jsonc
-// locales/ko/backend.json
-{ "mail": { "welcome": { "subject": "{{name}}님, 환영합니다" } } }
+```json
+// domain/locales/ko/backend.json
+{
+  "mail": { "welcome": { "subject": "{{name}}님, 환영합니다" } },
+  "validation": { "required": "필수 입력 항목입니다." }
+}
 ```
 ```ts fragment
 import { t } from 'gaonjs/i18n'
 const subject = t('mail.welcome.subject', { name: user.name })
 ```
 
-### (d) 레거시 단일 파일에서 이관
+### (d) 그 앱 컨트롤러 전용 서버 문구
+
+```json
+// apps/web/locales/ko/backend.json
+{ "flash": { "saved": "저장했습니다." } }
+```
+```ts controller-action
+async update() {
+  this.flash('notice', t('flash.saved'))     // web 스코프에서만 보이는 키
+  return this.redirect('/posts')
+}
+```
+
+### (e) 옛 배치에서 이관 (결정 459 · breaking)
 
 ```bash
-gaon doctor            # i18n-layout 경고 — 클라 t() 를 쓸 수 없는 상태
-gaon doctor --fix      # locales/ko.json → locales/ko/backend.json (내용·키 무변경)
-# 화면에 보이는 문구만 locales/ko/frontend.json 으로 옮긴다(사람의 판단 — 노출 방향)
-gaon gen
+gaon doctor            # i18n-layout — 루트 locales/ · 앱 평면 파일 · i18n.dir 을 전부 지목
+gaon doctor --fix --yes
+#   locales/<로케일>/backend.json  → domain/locales/<로케일>/backend.json   (이동)
+#   locales/<로케일>.json          → domain/locales/<로케일>/backend.json   (이동 · 미분류는 서버 전용)
+#   apps/<앱>/locales/<로케일>.json → apps/<앱>/locales/<로케일>/frontend.json (이동)
+#   locales/<로케일>/frontend.json → 전 앱 frontend.json 에 복제 후 원본 제거
+# 그 뒤 각 앱이 안 쓰는 키는 사람이 지운다(전 앱 복제는 되돌리기 쉬운 방향의 자동화)
+gaon gen && gaon check
 ```
 
 ## 알려진 함정
 
+- **루트 `locales/` 는 더 이상 읽히지 않는다**(결정 459) — 그대로 두면 전 화면·전 메일이
+  키 문자열로 degrade 한다. `gaon doctor --fix` 로 이관한다.
+- **도메인 코드에서 앱 키를 쓰지 말 것** — 요청 안에서는 우연히 해석되고 워커·크론에서만
+  빈다. `i18n-server-scope` 가 잡는다(§3 ⚠️).
+- **`shared/` 가 쓰는 키는 전 앱에 둘 것** — 한 앱에만 있으면 다른 앱에서만 키가 뜬다(§10).
 - **클라에서 backend 키를 쓰지 말 것** — 컴파일 에러로 막힌다. 그 문구가 화면에도 필요하면
   `frontend.json` 으로 **옮긴다**(양쪽에 복사하면 부팅 에러).
 - **다른 앱 전용 키를 쓰지 말 것** — 타입은 프로젝트 전체 frontend 합집합이라 통과하지만
   (앱별 유니온은 TS2717 로 구조적으로 불가), 그 앱 번들에는 없어서 화면에 키 문자열이
-  그대로 뜬다. `gaon doctor` 의 `i18n-app-scope` 가 잡는다.
+  그대로 뜬다. `i18n-app-scope` 가 잡는다.
+- **파일은 앱별인데 타입은 전역이다** — 카탈로그를 앱 폴더로 나눠도 키 유니온은 프로젝트
+  전체다(§4). "앱을 나눴으니 타입도 갈렸겠지" 가 이 배치의 가장 큰 오해다.
+- **`domain/locales/<로케일>/frontend.json` 은 만들 수 없다** — 도메인은 화면을 소유하지
+  않는다. 부팅에서 실패하고 doctor 가 error 로 짚는다.
+- **`i18n.dir` 은 제거됐다**(결정 459) — 위치가 관례로 고정이라 설정이 없다. 남아 있으면
+  doctor error(효과 없는 설정을 조용히 두면 "설정한 폴더를 읽겠지" 라는 오해가 된다).
 - **`.vue` 에서 서버 `t`(`gaonjs/i18n`)를 import 하지 말 것** — ALS 기반 서버 전용이다.
   클라는 `gaonjs/vue` 의 `t`.
 - **`v-html` + `t()` + 사용자 입력 조합 금지** — 템플릿 텍스트 보간(`{{ t(...) }}`)은 Vue 가
@@ -292,28 +386,29 @@ gaon gen
   로케일인지 짚어 준다.
 - **잡·크론은 로케일을 페이로드에 싣는다** — 요청 밖이라 ALS 가 없다(`runWithLanguage`).
 - **메일은 요청 로케일이 아니라 수신자 로케일** — `deliver(data, { locale })`(결정 160).
-- **`i18n.dir`·`fallbackLng` 는 문자열 리터럴로**(결정 412) — 변수·env 표현식은 타입 축과
-  doctor 가 정적으로 못 읽는다.
+- **`fallbackLng` 는 문자열 리터럴로**(결정 412) — 변수·env 표현식은 타입 축과 doctor 가
+  정적으로 못 읽는다.
 - **`supportedLngs: []`(빈 배열)은 "미지정" 과 같다**(결정 414).
-- **`gaon check` 가 부팅 조건을 먼저 본다**(결정 413) — 카탈로그가 비었거나 `fallbackLng`
-  가 지목한 카탈로그가 없으면 check 가 실패한다.
-- **검증 실패 문안은 backend** — 예약 namespace `validation.<code>` 를 `backend.json` 에
-  두면 서버가 요청 로케일로 번역한다(결정 183).
+- **`gaon check` 가 부팅 조건을 먼저 본다**(결정 413) — 카탈로그가 하나도 없거나
+  `fallbackLng` 가 지목한 카탈로그가 없으면 check 가 실패한다.
+- **검증 실패 문안은 도메인 backend** — 예약 namespace `validation.<code>` 를
+  `domain/locales/<로케일>/backend.json` 에 두면 서버가 요청 로케일로 번역한다(결정 183).
 
 ## 관련 결정 번호
 
 | 결정 | 요지 |
 |---|---|
-| §7 (v0.15) | i18n 배터리 · locales/ 카탈로그 · t() |
+| §7 (v0.15) | i18n 배터리 · 카탈로그 · t() |
 | 결정 158 (13차 W2) | `.gaon/messages.d.ts` 키 타입 브리지 — 없는 키 컴파일 에러 |
 | 결정 159 (13차 W1) | 요청별 로케일 자동 협상 · `this.setLocale` · detect 설정 |
 | 결정 181 | 복수형 base 키 노출(`t('cart.items', { count })`) |
 | 결정 213 | (구) Vue 소비 = 서버 주도 render props/sharedProps 만 — **결정 454 로 부분 번복**(§6 탈출구로 존속) |
 | 결정 214 (13차 W2) | 최초 문서 셸 `<html lang>` 이 협상 로케일 자동 추종 |
-| 결정 216 (13차 W4) | `locale-parity` 경고 — 결정 454 로 **스코프별 비교** |
-| 결정 352 | 기준 로케일 = `fallbackLng` · `i18n.dir` 존중 |
+| 결정 216 (13차 W4) | `locale-parity` 경고 — 결정 454·459 로 **스코프별 비교** |
+| 결정 352 | 기준 로케일 = `fallbackLng` |
 | 결정 353 · 413 | 빈 카탈로그·지목 로케일 부재 = 부팅 fail-loud + check 사전 검사 |
 | 결정 412 · 414 | i18n config 정적 분석 범위·경고 · 생성 키 이스케이프 · `supportedLngs: []` |
-| **결정 455** | 런타임 없는키 = **키 렌더 + 경고**(서버·클라 동일) · 요청/화면을 죽이지 않는다 · 폴백 해석은 유지 · 정적 키는 컴파일에서 차단(2단) |
-| **결정 454** | **클라 `t()`(`gaonjs/vue`) · backend/frontend 폴더 레이아웃 · 두 갈래 타입 · 앱별 카탈로그 청크(immutable·seal 면제) · 공유 prop `locale`(연성 예약) · doctor `i18n-layout`·`i18n-app-scope`** |
-| **결정 456** | **`locale-parity` 앱 스코프 확장**(§9) — `apps/<앱>/locales/` 를 앱 내부에서 비교(스코프 `app:<앱>`). 결정 454 가 정본 배치로 지정한 경로가 커버리지 밖이라 앱 카탈로그의 로케일 누락이 정적으로 안 잡혔다(auction 실측 · 이 문서 정본 예시는 이미 `locale-parity` 를 약속하고 있었다). 루트 교차 비교는 기각(앱 전용 키가 전량 오탐) · `i18n-app-scope` 재사용도 기각(그 검사의 키 집합은 전 로케일 합집합이라 축이 다름) |
+| 결정 455 | 런타임 없는키 = **키 렌더 + 경고**(서버·클라 동일) · 요청/화면을 죽이지 않는다 · 정적 키는 컴파일에서 차단(2단) |
+| 결정 454 | 클라 `t()`(`gaonjs/vue`) · backend/frontend 스코프 분리 · 두 갈래 타입 · 앱별 카탈로그 청크(immutable·seal 면제) · 공유 prop `locale` |
+| 결정 456 | `locale-parity` 앱 스코프 확장 — 앱 내부에서 비교(루트 교차 비교는 오탐이라 기각) |
+| **결정 459** | **소유자 2개로 재편**(결정 454 부분 반전) — 루트 공용 `locales/` **폐지** · 화면 문구 = `apps/<앱>/locales/<로케일>/frontend.json`(필수) · 앱 서버 문구 = 같은 폴더 `backend.json`(선택) · 도메인 공통 = `domain/locales/<로케일>/backend.json` · 서버 `t()` 는 `app:<앱>` → `domain` 네임스페이스 폴백(앱 ALS) · 소유자 간 키 충돌 = 부팅 fail-loud · `i18n.dir` 제거 · `domain/locales/*/frontend.json` = error · shared 키는 전 앱 복제 + doctor 강제 · 신규 검사 `i18n-server-scope` · 타입 유니온은 **여전히 프로젝트 전역**(TS2717) |

package/dist/templates/project/agents/web.md.tpl

@@ -312,8 +312,9 @@ const form = useForm({ title: '', body: '' })
 #### 검증 사유 로케일화 — 예약 namespace `validation.*` (결정 183)
 
 검증 실패의 **필드별 사유**(`form.errors.<필드>` 로 엔드유저에 노출되는 부분)는 요청
-로케일로 번역된다 — `i18n` 이 설정돼 있고 앱이 `locales/<lng>.json` 의 **예약 namespace
-`validation.<code>`** 로 번역을 제공하면. 프레임웍은 **안정적 코드만** 노출하고 번역은
+로케일로 번역된다 — `i18n` 이 설정돼 있고 프로젝트가 `domain/locales/<로케일>/backend.json`
+의 **예약 namespace `validation.<code>`** 로 번역을 제공하면(결정 459 — 검증 문안은 화면
+밖 문구라 도메인이 소유한다). 프레임웍은 **안정적 코드만** 노출하고 번역은
 앱 몫이다(The One Way: 코드는 프레임웍, 문안은 앱). 키가 없으면 내장 fallback(한국어)로
 떨어져 거동이 보존된다. i18n 미설정이면 항상 fallback.
 
@@ -330,7 +331,7 @@ const form = useForm({ title: '', body: '' })
 | `invalid` | — | 그 외 coerce 예외(비-CoerceError) |
 
 ```json
-// locales/en.json — 앱이 검증 문안을 로케일별로 준다(i18next {{max}} 보간).
+// domain/locales/en/backend.json — 검증 문안을 로케일별로 준다(i18next {{max}} 보간).
 { "validation": {
     "required": "This field is required.",
     "too_long": "At most {{max}} characters (got {{len}})."

package/dist/templates/project/{locales → apps/web/locales}/en/frontend.json.tpl

@@ -1,5 +1,6 @@
 {
   "nav": { "home": "Home" },
+  "home": { "tagline": "You are on Gaon." },
   "common": {
     "loading": "Checking status…",
     "items_one": "{{count}} item",

package/dist/templates/project/{locales → apps/web/locales}/ko/frontend.json.tpl

@@ -1,5 +1,6 @@
 {
   "nav": { "home": "홈" },
+  "home": { "tagline": "가온에 올라탔습니다." },
   "common": {
     "loading": "상태 확인 중…",
     "items_other": "항목 {{count}}개"

package/dist/templates/project/gaon.config.ts.tpl

@@ -54,11 +54,12 @@ export default defineConfig({
       }
     : undefined,
 
-  // 다국어(§7 · 결정 454). 카탈로그는 언어별 폴더 + 스코프 분리다:
-  //   locales/<로케일>/frontend.json — 화면 문구. 클라 t()(gaonjs/vue)가 쓰고 앱 번들 청크로 나간다.
-  //   locales/<로케일>/backend.json  — 메일·잡·검증 등 **서버 전용**. 클라로 나가지 않는다.
-  //   apps/<앱>/locales/<로케일>.json — 그 앱 전용 화면 문구(그 앱 청크에만 실린다).
-  // 요청 로케일은 세션>쿠키>Accept-Language 로 자동 협상된다(결정 159 · this.setLocale 로 전환).
+  // 다국어(§7 · 결정 459). 문구의 **소유자**가 위치를 정한다 — 화면이면 그 앱, 화면 밖이면 domain:
+  //   apps/<앱>/locales/<로케일>/frontend.json — 그 앱 화면 문구. 클라 t()(gaonjs/vue) · 그 앱 청크로만 나간다.
+  //   apps/<앱>/locales/<로케일>/backend.json  — 그 앱 컨트롤러 전용 서버 문구(선택).
+  //   domain/locales/<로케일>/backend.json     — 메일·잡·검증 등 도메인 공통 **서버 전용**. 클라로 나가지 않는다.
+  // 위치는 관례로 고정이라 dir 설정이 없다. 요청 로케일은 세션>쿠키>Accept-Language 로
+  // 자동 협상된다(결정 159 · this.setLocale 로 전환).
   i18n: { fallbackLng: 'ko', supportedLngs: ['ko', 'en'] },
 
   // 웹 서버 리슨 옵션. --port · env PORT 로 덮을 수 있다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.64.0",
+  "version": "0.65.2",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
@@ -32,15 +32,15 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/data": "0.26.2",
-    "@gaonjs/i18n": "0.4.1",
-    "@gaonjs/config": "0.25.12",
     "@gaonjs/async": "0.22.0",
-    "@gaonjs/mail": "0.5.3",
+    "@gaonjs/config": "0.26.1",
     "@gaonjs/core": "0.3.0",
-    "@gaonjs/web": "0.32.1"
+    "@gaonjs/data": "0.26.3",
+    "@gaonjs/i18n": "0.5.0",
+    "@gaonjs/web": "0.33.0",
+    "@gaonjs/mail": "0.5.4"
   },
   "scripts": {
-    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"const fs=require('fs');fs.cpSync('src/templates','dist/templates',{recursive:true,filter:(s)=>!s.endsWith('.ts')});fs.rmSync('dist/templates/index.ts',{force:true})\""
+    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"const fs=require('fs');fs.rmSync('dist/templates/project',{recursive:true,force:true});fs.cpSync('src/templates','dist/templates',{recursive:true,filter:(s)=>!s.endsWith('.ts')});fs.rmSync('dist/templates/index.ts',{force:true})\""
   }
 }

package/dist/templates/project/apps/web/locales/en.json.tpl

@@ -1,3 +0,0 @@
-{
-  "home": { "tagline": "You are on Gaon." }
-}

package/dist/templates/project/apps/web/locales/ko.json.tpl

@@ -1,3 +0,0 @@
-{
-  "home": { "tagline": "가온에 올라탔습니다." }
-}