@gaonjs/cli 0.61.0 → 0.62.1

package/dist/commands/check.js

@@ -255,15 +255,20 @@ function verifyI18nCatalogs(cwd) {
     const resources = existsSync(abs) ? loadLocales(abs) : {};
     if (Object.keys(resources).length === 0) {
         return (`i18n 이 설정됐지만 로케일 카탈로그가 비어 있습니다: ${abs}\n` +
-            `  → ${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}.json 을 만들거나(최소 fallbackLng 카탈로그),\n` +
+            `  → ${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}/frontend.json (화면 문구) 또는 ` +
+            `${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}/backend.json (서버 전용 문구)을 만드세요 — 결정 454.\n` +
+            `  → 단일 파일 레이아웃(${dir}/${cfg.fallbackLng ?? '<fallbackLng>'}.json)도 계속 지원합니다(서버 전용으로 취급).\n` +
             `  → gaon.config.ts 의 i18n.dir 이 실제 카탈로그 폴더를 가리키는지 확인하세요.\n` +
             `  (이 상태로는 gaon serve 가 부팅에서 실패합니다 — 결정 353)`);
     }
     const wanted = [...(cfg.fallbackLng ? [cfg.fallbackLng] : []), ...(cfg.supportedLngs ?? [])];
     const missing = wanted.filter((lng, i, arr) => arr.indexOf(lng) === i && !resources[lng]);
     if (missing.length > 0) {
-        return (`i18n 설정이 지목한 로케일의 카탈로그 파일이 없습니다: ${missing.join(', ')}\n` +
-            `  → ${dir}/ 에 ${missing.map((l) => `${l}.json`).join(' · ')} 을 추가하거나,\n` +
+        return (`i18n 설정이 지목한 로케일의 카탈로그가 없습니다: ${missing.join(', ')}\n` +
+            `  → ${dir}/ 에 ${missing.map((l) => `${l}/frontend.json`).join(' · ')} (또는 ${missing
+                .map((l) => `${l}/backend.json`)
+                .join(' · ')})을 추가하거나,\n` +
+            `  → 단일 파일 레이아웃이면 ${missing.map((l) => `${l}.json`).join(' · ')} 을 추가하거나,\n` +
             `  → gaon.config.ts 의 fallbackLng/supportedLngs 에서 해당 로케일을 제거하세요.\n` +
             `  (이 상태로는 gaon serve 가 부팅에서 실패합니다 — 결정 353)`);
     }

package/dist/dev.d.ts

@@ -4,6 +4,16 @@ export interface DevApp {
     readonly appDir: string;
     /** apps/<app>/.gaon/routes.d.ts */
     readonly routesOut: string;
+    /** apps/<app>/locales (앱 전용 frontend 카탈로그 · 결정 454). */
+    readonly localesDir: string;
+    /** apps/<app>/.gaon/messages.catalog.ts (클라 카탈로그 값 모듈 · 결정 454). */
+    readonly catalogOut: string;
+}
+/** 메시지 축이 카탈로그 모듈을 낼 앱 참조(결정 454 · messages-gen.MessagesApp 과 구조 호환). */
+export interface MessagesAppRef {
+    readonly name: string;
+    readonly localesDir: string;
+    readonly catalogOut: string;
 }
 export interface DevLayout {
     /** domain/schema (없으면 undefined — tables 워치 생략). */
@@ -28,8 +38,11 @@ export interface DevDeps {
     readonly layout: DevLayout;
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
+    /**
+     * locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352) + 앱별
+     * messages.catalog.ts (결정 454 · apps 를 넘긴 호출자만). i18n 축을 쓰는 호출자만 준다.
+     */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string, apps?: readonly MessagesAppRef[]): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
     watch(dir: string, opts: WatchOptions): WatchHandle;
@@ -60,8 +73,8 @@ export declare function startDev(deps: DevDeps): Promise<DevHandle>;
 export interface RegenDeps {
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
+    /** locales/ → .gaon/messages.d.ts + 앱별 messages.catalog.ts (결정 158 · 352 · 454). */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string, apps?: readonly MessagesAppRef[]): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
 }

package/dist/dev.js

@@ -40,7 +40,7 @@ export async function startDev(deps) {
     }
     // 결정 158(W2): locales/ → messages.d.ts.
     if (layout.localesDir && deps.regenerateMessages) {
-        await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng);
+        await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng, messagesAppsOf(layout));
         deps.log({ kind: 'regen', target: 'messages' });
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts(VITE_* 타입 브리지). `.env` 부재는
@@ -80,7 +80,7 @@ export async function startDev(deps) {
         handles.push(deps.watch(localesDir, {
             filter: isMessagesChange,
             onChange: async () => {
-                await regenerateMessages(localesDir, layout.messagesOut, layout.messagesBaseLng);
+                await regenerateMessages(localesDir, layout.messagesOut, layout.messagesBaseLng, messagesAppsOf(layout));
                 deps.log({ kind: 'regen', target: 'messages' });
             },
             onError: deps.onError,
@@ -111,7 +111,8 @@ export async function regenerateGaonOnce(layout, deps) {
     // 결정 158(W2): locales/ 가 있으면 messages.d.ts 도 재생성한다(i18n 키 타입 브리지).
     let messages = false;
     if (layout.localesDir && deps.regenerateMessages) {
-        messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng)) === true;
+        messages =
+            (await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng, messagesAppsOf(layout))) === true;
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts. `.env` 부재는 throw(수리 안내).
     let env = false;
@@ -120,6 +121,10 @@ export async function regenerateGaonOnce(layout, deps) {
     }
     return { tables: !!layout.schemaDir, apps: layout.apps.map((a) => a.name), messages, env };
 }
+/** 결정 454: 레이아웃의 앱 목록을 메시지 축 입력(카탈로그 모듈 경로)으로 좁힌다. */
+function messagesAppsOf(layout) {
+    return layout.apps.map((a) => ({ name: a.name, localesDir: a.localesDir, catalogOut: a.catalogOut }));
+}
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export function resolveDevLayout(cwd) {
     const root = resolve(cwd);
@@ -142,6 +147,8 @@ export function resolveDevLayout(cwd) {
                 name: entry.name,
                 appDir,
                 routesOut: join(appDir, '.gaon', 'routes.d.ts'),
+                localesDir: join(appDir, 'locales'),
+                catalogOut: join(appDir, '.gaon', 'messages.catalog.ts'),
             });
         }
     }

package/dist/doctor/fixers/i18n-layout.d.ts

@@ -0,0 +1,7 @@
+import type { DoctorCheck } from '../types.js';
+import type { FixerPlan } from './types.js';
+/**
+ * i18n-layout 위반(레거시 단일 파일)을 폴더 레이아웃으로 옮기는 계획을 만든다.
+ * 내용은 그대로다 — 키 이름도 바뀌지 않는다(결정 454 R4).
+ */
+export declare function fixI18nLayout(issues: readonly DoctorCheck[], cwd: string): Promise<readonly FixerPlan[]>;

package/dist/doctor/fixers/i18n-layout.js

@@ -0,0 +1,40 @@
+// @gaonjs/cli · doctor fixer · 레거시 단일 파일 카탈로그 → 폴더 레이아웃 이관 (결정 454)
+//
+// `locales/<로케일>.json` → `locales/<로케일>/backend.json` **이동만** 한다(rename 계획).
+//
+// **왜 전량 backend 인가(안전 방향 자동화)**: 자동 분류가 오판하면 서버 전용 문구를
+// frontend 로 보내 클라 번들·CDN 캐시에 노출된다 — 되돌리기 어려운 방향의 사고다.
+// 되돌리기 쉬운 방향(전량 backend = 클라에서 안 보임)으로만 자동화하고, 화면 문구를
+// frontend.json 으로 옮기는 판단은 사람이 한다(doctor 경고가 그 다음 단계를 안내).
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * i18n-layout 위반(레거시 단일 파일)을 폴더 레이아웃으로 옮기는 계획을 만든다.
+ * 내용은 그대로다 — 키 이름도 바뀌지 않는다(결정 454 R4).
+ */
+export async function fixI18nLayout(issues, cwd) {
+    const plans = [];
+    for (const issue of issues) {
+        const to = issue.detail?.to;
+        if (typeof to !== 'string' || issue.file === undefined)
+            continue;
+        let before;
+        try {
+            before = await readFile(join(cwd, issue.file), 'utf8');
+        }
+        catch {
+            continue; // 그 사이 파일이 사라졌으면 계획에서 제외(상위가 부분 적용을 감당하지 않게).
+        }
+        plans.push({
+            kind: 'rename',
+            file: issue.file,
+            to,
+            before,
+            summary: `카탈로그를 폴더 레이아웃으로 이동: ${issue.file} → ${to} (결정 454)\n` +
+                `  내용·키는 그대로다. 이 상태에서는 **서버 전용**(클라로 나가지 않음)이다.\n` +
+                `  → 화면에 보이는 문구만 같은 폴더의 frontend.json 으로 옮긴 뒤 gaon gen 을 실행하세요.`,
+            refEdits: [], // JSON 카탈로그는 소스가 import 하지 않는다(경로 참조 갱신 없음).
+        });
+    }
+    return plans;
+}

package/dist/doctor/fixers/index.d.ts

@@ -5,6 +5,7 @@ export { fixDependencyDirection, fixDomainToSharedTypeOnly, } from './dependency
 export { fixSchemaFilename, rewriteSchemaImport } from './schema-filename.js';
 export { fixModelFilename, rewriteModelImport } from './model-filename.js';
 export { fixSealClientWiring, wireSealClient } from './seal-client-wiring.js';
+export { fixI18nLayout } from './i18n-layout.js';
 /**
  * 규칙별 fixer 표. 없는 규칙(값 undefined)은 "수동 수정 필요" 로 리포트된다.
  * 새 fixer 를 만들면 이 표에만 추가하면 된다(runDoctorFix 는 표를 순회).

package/dist/doctor/fixers/index.js

@@ -10,10 +10,12 @@ import { fixDependencyDirection } from './dependency-direction.js';
 import { fixSchemaFilename } from './schema-filename.js';
 import { fixModelFilename } from './model-filename.js';
 import { fixSealClientWiring } from './seal-client-wiring.js';
+import { fixI18nLayout } from './i18n-layout.js';
 export { fixDependencyDirection, fixDomainToSharedTypeOnly, } from './dependency-direction.js';
 export { fixSchemaFilename, rewriteSchemaImport } from './schema-filename.js';
 export { fixModelFilename, rewriteModelImport } from './model-filename.js';
 export { fixSealClientWiring, wireSealClient } from './seal-client-wiring.js';
+export { fixI18nLayout } from './i18n-layout.js';
 /**
  * 규칙별 fixer 표. 없는 규칙(값 undefined)은 "수동 수정 필요" 로 리포트된다.
  * 새 fixer 를 만들면 이 표에만 추가하면 된다(runDoctorFix 는 표를 순회).
@@ -23,6 +25,7 @@ export const FIXERS = {
     'schema-filename': fixSchemaFilename,
     'model-filename': fixModelFilename,
     'seal-security': fixSealClientWiring,
+    'i18n-layout': fixI18nLayout,
 };
 /**
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
@@ -35,6 +38,16 @@ export const FIXERS = {
  * (`fixers/capabilities.test.ts` · ALL_RULES ↔ 카탈로그 대칭).
  */
 export const FIXER_CAPABILITIES = [
+    {
+        rule: 'i18n-layout',
+        hasFixer: true,
+        note: '자동 · locales/<로케일>.json → locales/<로케일>/backend.json 이동(결정 454). 화면 문구를 frontend.json 으로 나누는 것은 노출 방향이라 사람이 판단한다.',
+    },
+    {
+        rule: 'i18n-app-scope',
+        hasFixer: false,
+        note: '수동 · 그 키를 이 앱 카탈로그(apps/<앱>/locales/<로케일>.json) 또는 공용 locales/<로케일>/frontend.json 에 추가(어느 앱 문구인지는 설계 판단).',
+    },
     {
         rule: 'response-mixing',
         hasFixer: false,

package/dist/doctor/i18n-app-scope.d.ts

@@ -0,0 +1,8 @@
+import type { RuleReport } from './types.js';
+/**
+ * 주석을 공백으로 지운다(문자열 리터럴 안의 `//`·`/*` 는 보존). 스캐폴드·문서 주석이
+ * 예시로 적은 `t('키')` 를 실 호출로 오인해 **오탐 에러**를 내던 것을 막는다(브라우저 e2e
+ * 게이트가 실제로 잡았다). 길이를 보존해 라인 번호 계산이 어긋나지 않는다.
+ */
+export declare function stripComments(src: string): string;
+export declare function checkI18nAppScope(cwd: string): Promise<RuleReport>;

package/dist/doctor/i18n-app-scope.js

@@ -0,0 +1,178 @@
+// @gaonjs/cli · doctor · 앱 경계를 넘는 클라 번역 키 (결정 454 · 에러)
+//
+// **왜 doctor 가 필요한가(타입으로 못 잡는 축)**: 두 앱이 `GaonMessages.keys` 를 서로 다른
+// 유니온으로 augment 하면 TS2717(Subsequent property declarations must have the same type)이
+// 나고, `gaon check` 는 단일 tsc 프로그램이라 앱별 클라 키 유니온을 만들 수 없다(실측 · 결정 454).
+// 그래서 클라 키 유니온은 **프로젝트 전체 frontend 합집합**이고, 앱 경계는 두 층이 강제한다:
+//   · 런타임 = 앱 청크에 그 앱 카탈로그만 실린다(물리적).
+//   · 정적   = 이 검사 — 앱 코드가 **다른 앱 전용 키**를 쓰면 에러로 잡는다.
+//
+// 그냥 두면 컴파일은 통과하고 화면에는 키 문자열이 그대로 뜬다(조용한 실패).
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { flattenKeys, loadAppLocales, loadScopedLocales, withPluralBaseKeys } from '@gaonjs/i18n';
+import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
+// `import { t } from 'gaonjs/vue'` 를 쓴 파일에서만 본다 — 서버 t(gaonjs/i18n)는 대상이 아니다.
+const CLIENT_T_IMPORT = /from\s+['"]gaonjs\/vue['"]/;
+// t('key') · t("key") · t(`key`) 의 리터럴 키만 본다(동적 키는 정적 검출 대상 아님).
+const T_CALL = /\bt\(\s*['"`]([^'"`]+)['"`]/g;
+/**
+ * 주석을 공백으로 지운다(문자열 리터럴 안의 `//`·`/*` 는 보존). 스캐폴드·문서 주석이
+ * 예시로 적은 `t('키')` 를 실 호출로 오인해 **오탐 에러**를 내던 것을 막는다(브라우저 e2e
+ * 게이트가 실제로 잡았다). 길이를 보존해 라인 번호 계산이 어긋나지 않는다.
+ */
+export function stripComments(src) {
+    const out = src.split('');
+    let i = 0;
+    let state = 'code';
+    const blank = (from, to) => {
+        for (let k = from; k < to; k++)
+            if (out[k] !== '\n')
+                out[k] = ' ';
+    };
+    while (i < src.length) {
+        const two = src.slice(i, i + 2);
+        if (state === 'code') {
+            if (two === '//') {
+                const end = src.indexOf('\n', i);
+                const stop = end === -1 ? src.length : end;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            if (two === '/*') {
+                const end = src.indexOf('*/', i + 2);
+                const stop = end === -1 ? src.length : end + 2;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            if (src.startsWith('<!--', i)) {
+                const end = src.indexOf('-->', i + 4);
+                const stop = end === -1 ? src.length : end + 3;
+                blank(i, stop);
+                i = stop;
+                continue;
+            }
+            const c = src[i];
+            if (c === "'")
+                state = 'single';
+            else if (c === '"')
+                state = 'double';
+            else if (c === '`')
+                state = 'tick';
+            i++;
+            continue;
+        }
+        // 문자열 안 — 이스케이프를 건너뛰고 닫는 따옴표에서 code 로 돌아간다.
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if ((state === 'single' && c === "'") || (state === 'double' && c === '"') || (state === 'tick' && c === '`')) {
+            state = 'code';
+        }
+        i++;
+    }
+    return out.join('');
+}
+const SOURCE_EXT = ['.vue', '.ts'];
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.gaon']);
+function walk(dir, out = []) {
+    if (!existsSync(dir))
+        return out;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') && entry.name !== '.gaon')
+            continue;
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const p = join(dir, entry.name);
+        if (entry.isDirectory())
+            walk(p, out);
+        else if (SOURCE_EXT.some((e) => entry.name.endsWith(e)))
+            out.push(p);
+    }
+    return out;
+}
+/** 그 앱의 클라가 실제로 받는 키 집합 = 공용 frontend ∪ 자기 앱 카탈로그(전 로케일 합집합). */
+function keysForApp(localesDir, appLocalesDir) {
+    const scoped = loadScopedLocales(localesDir);
+    const keys = new Set();
+    for (const res of Object.values(scoped.frontend)) {
+        for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
+            keys.add(k);
+    }
+    for (const res of Object.values(loadAppLocales(appLocalesDir))) {
+        for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
+            keys.add(k);
+    }
+    return keys;
+}
+/** 프로젝트 전체(모든 앱)의 클라 키 — "다른 앱에는 있는 키" 인지 구분해 안내를 정확히 한다. */
+function allClientKeys(localesDir, appDirs) {
+    const keys = keysForApp(localesDir, '');
+    for (const appDir of appDirs) {
+        for (const res of Object.values(loadAppLocales(join(appDir, 'locales')))) {
+            for (const k of withPluralBaseKeys(flattenKeys(res.translation)))
+                keys.add(k);
+        }
+    }
+    return keys;
+}
+export async function checkI18nAppScope(cwd) {
+    const appsDir = join(cwd, 'apps');
+    if (!existsSync(appsDir))
+        return { rule: 'i18n-app-scope', issues: [] };
+    const cfg = analyzeProjectI18n(cwd);
+    const localesDir = resolveLocalesDir(cwd, cfg.dir);
+    if (!existsSync(localesDir))
+        return { rule: 'i18n-app-scope', issues: [] };
+    const appDirs = readdirSync(appsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => join(appsDir, e.name));
+    // frontend 카탈로그가 하나도 없으면(레거시 레이아웃) 클라 t() 자체가 없다 — 무소음.
+    const scoped = loadScopedLocales(localesDir);
+    if (Object.keys(scoped.frontend).length === 0)
+        return { rule: 'i18n-app-scope', issues: [] };
+    const everyKey = allClientKeys(localesDir, appDirs);
+    const issues = [];
+    for (const appDir of appDirs) {
+        const appLocales = join(appDir, 'locales');
+        const own = keysForApp(localesDir, appLocales);
+        for (const file of walk(appDir)) {
+            if (!statSync(file).isFile())
+                continue;
+            const raw = readFileSync(file, 'utf8');
+            if (!CLIENT_T_IMPORT.test(raw))
+                continue;
+            // 주석 안 예시(`t('키')` 같은 설명)를 실 호출로 세지 않는다 — 오탐은 빌드를 세운다.
+            const src = stripComments(raw);
+            for (const m of src.matchAll(T_CALL)) {
+                const key = m[1];
+                if (own.has(key))
+                    continue;
+                const line = src.slice(0, m.index).split('\n').length;
+                const rel = relative(cwd, file);
+                const elsewhere = everyKey.has(key);
+                issues.push({
+                    rule: 'i18n-app-scope',
+                    level: 'error',
+                    file: rel,
+                    line,
+                    message: elsewhere
+                        ? `'${key}' 는 **다른 앱 전용** 번역 키입니다 — 이 앱의 카탈로그에 없습니다: ${rel}:${line} (결정 454)\n` +
+                            `  앱 번들에는 그 앱 카탈로그만 실리므로 런타임에 번역 대신 키 문자열이 그대로 보입니다.\n` +
+                            `→ 이 앱에서도 쓸 문구면 공용 ${relative(cwd, join(localesDir, '<로케일>', 'frontend.json'))} 로 옮기고,\n` +
+                            `→ 이 앱 전용 문구면 ${relative(cwd, join(appLocales, '<로케일>.json'))} 에 추가한 뒤 gaon gen 을 실행하세요.`
+                        : `'${key}' 를 어느 카탈로그에서도 찾을 수 없습니다: ${rel}:${line} (결정 454)\n` +
+                            `→ ${relative(cwd, join(appLocales, '<로케일>.json'))}(앱 전용) 또는 ` +
+                            `${relative(cwd, join(localesDir, '<로케일>', 'frontend.json'))}(앱 공용)에 키를 추가하고 gaon gen 을 실행하세요.\n` +
+                            `  (서버 전용 문구는 backend.json 에 두고 서버 t()(gaonjs/i18n)로 쓰세요 — 클라로 나가지 않습니다.)`,
+                    detail: { key, app: relative(cwd, appDir), definedInAnotherApp: elsewhere },
+                });
+            }
+        }
+    }
+    return { rule: 'i18n-app-scope', issues };
+}

package/dist/doctor/i18n-layout.d.ts

@@ -0,0 +1,4 @@
+import type { RuleReport } from './types.js';
+/** 레거시 단일 파일 로케일 목록(폴더 레이아웃과 공존하면 로더가 별도로 fail-loud). */
+export declare function legacyLocaleFiles(localesDir: string): string[];
+export declare function checkI18nLayout(cwd: string): Promise<RuleReport>;

package/dist/doctor/i18n-layout.js

@@ -0,0 +1,47 @@
+// @gaonjs/cli · doctor · i18n 카탈로그 레이아웃 안내 (결정 454 · 경고)
+//
+// 결정 454 의 정본 저작 레이아웃은 언어별 폴더 + 스코프 분리다:
+//   locales/<로케일>/backend.json  — 메일·잡·검증 등 **서버 전용**(클라로 안 나감)
+//   locales/<로케일>/frontend.json — 화면 문구(클라 t() 가 쓰는 카탈로그)
+//
+// 레거시 단일 파일(`locales/<로케일>.json`)도 계속 **동작**하지만, 미분류 카탈로그는
+// 안전 기본으로 전량 backend 취급이라 **클라 `t()` 를 쓸 수 없다**(클라 키 축 미생성).
+// 그 사실을 조용히 두면 "왜 gaonjs/vue 의 t 가 키를 그대로 뱉지?" 로 시간을 태운다 —
+// 경고로 짚고 `--fix` 로 폴더 이관까지 해 준다(노출 방향 자동 분류는 하지 않는다).
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
+/** 레거시 단일 파일 로케일 목록(폴더 레이아웃과 공존하면 로더가 별도로 fail-loud). */
+export function legacyLocaleFiles(localesDir) {
+    if (!existsSync(localesDir))
+        return [];
+    return readdirSync(localesDir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.json'))
+        .map((e) => basename(e.name, '.json'))
+        .sort();
+}
+export async function checkI18nLayout(cwd) {
+    const cfg = analyzeProjectI18n(cwd);
+    const localesDir = resolveLocalesDir(cwd, cfg.dir);
+    if (!existsSync(localesDir))
+        return { rule: 'i18n-layout', issues: [] };
+    const legacy = legacyLocaleFiles(localesDir);
+    if (legacy.length === 0)
+        return { rule: 'i18n-layout', issues: [] };
+    const issues = legacy.map((lng) => {
+        const rel = relative(cwd, join(localesDir, `${lng}.json`));
+        const dirRel = relative(cwd, join(localesDir, lng));
+        return {
+            rule: 'i18n-layout',
+            level: 'warning',
+            file: rel,
+            message: `로케일 '${lng}' 이 단일 파일 레이아웃입니다: ${rel} (결정 454)\n` +
+                `  이 카탈로그는 **서버 전용**으로 취급돼 클라이언트 t()(gaonjs/vue)가 쓸 수 없습니다.\n` +
+                `→ 자동 이관: gaon doctor --fix  (${rel} → ${dirRel}/backend.json)\n` +
+                `→ 그 뒤 화면에 보이는 문구만 ${dirRel}/frontend.json 으로 옮기고 gaon gen 을 실행하세요.\n` +
+                `  (frontend 만 클라 번들 청크로 나갑니다 — backend 문구는 노출되지 않습니다.)`,
+            detail: { locale: lng, from: rel, to: `${dirRel}/backend.json` },
+        };
+    });
+    return { rule: 'i18n-layout', issues };
+}

package/dist/doctor/locale-parity.js

@@ -10,7 +10,7 @@
 // 빌드를 세우지 않는다. --json 은 detail.locale·detail.missing 으로 구조화한다.
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { loadLocales, flattenKeys } from '@gaonjs/i18n';
+import { loadScopedLocales, flattenKeys } from '@gaonjs/i18n';
 import { analyzeProjectI18n, resolveLocalesDir } from '../i18n-config.js';
 // 경고 한 줄이 폭주하지 않게 나열 상한 — 넘으면 "…외 N개" 로 접는다(detail 에는 전량).
 const MAX_KEYS_SHOWN = 20;
@@ -32,10 +32,22 @@ export async function checkLocaleParity(cwd) {
     const localesDir = resolveLocalesDir(cwd, analyzeProjectI18n(cwd).dir);
     if (!existsSync(localesDir))
         return { rule: 'locale-parity', issues: [] };
-    const resources = loadLocales(localesDir);
+    // 결정 454: 스코프(backend·frontend)별로 따로 비교한다 — 같은 키를 로케일마다 다른
+    // 스코프에 두면(ko 는 frontend, ja 는 backend) 클라 카탈로그가 갈리므로, 병합본으로
+    // 비교하면 그 배치 불일치를 못 본다. 파일 경로도 스코프별로 정확히 짚는다.
+    const scoped = loadScopedLocales(localesDir);
+    const issues = [];
+    for (const scope of ['backend', 'frontend']) {
+        const resources = scoped[scope];
+        issues.push(...parityIssues(cwd, localesDir, resources, scoped.layout, scope));
+    }
+    return { rule: 'locale-parity', issues };
+}
+/** 한 스코프 안에서 로케일 간 키 diff 를 계산한다(레거시 단일 파일은 backend 스코프에 담긴다). */
+function parityIssues(cwd, localesDir, resources, layout, scope) {
     const langs = Object.keys(resources).sort();
     if (langs.length < 2)
-        return { rule: 'locale-parity', issues: [] };
+        return [];
     // 로케일별 키 집합과 전체 union(어느 로케일에든 등장한 키의 합집합)을 만든다.
     // 복수형 접미사는 base 로 정규화해 로케일별 정당한 복수형 차이를 오탐으로 잡지 않는다.
     const keysByLang = new Map();
@@ -52,7 +64,10 @@ export async function checkLocaleParity(cwd) {
         const missing = [...union].filter((k) => !have.has(k)).sort();
         if (missing.length === 0)
             continue;
-        const rel = relative(cwd, join(localesDir, `${lng}.json`));
+        // 파일 경로는 레이아웃에 맞춘다 — 폴더 분리면 <lng>/<scope>.json, 레거시면 <lng>.json.
+        const rel = layout[lng] === 'legacy'
+            ? relative(cwd, join(localesDir, `${lng}.json`))
+            : relative(cwd, join(localesDir, lng, `${scope}.json`));
         const shown = missing.slice(0, MAX_KEYS_SHOWN);
         const more = missing.length - shown.length;
         const list = shown.map((k) => `'${k}'`).join(', ') + (more > 0 ? ` …외 ${more}개` : '');
@@ -64,8 +79,8 @@ export async function checkLocaleParity(cwd) {
                 `  누락 키: ${list}\n` +
                 `→ ${rel} 에 이 키들을 채우세요 — 없으면 '${lng}' 사용자에게 fallback(대개 다른 언어)\n` +
                 `  번역이 조용히 노출됩니다. messages.d.ts 는 기준 로케일 기준이라 컴파일로 못 잡습니다(결정 216).`,
-            detail: { locale: lng, missing },
+            detail: { locale: lng, scope, missing },
         });
     }
-    return { rule: 'locale-parity', issues };
+    return issues;
 }

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'agents-docs-stale' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return' | 'channel-collision' | 'channel-instance-authorize' | 'dotenv-node-env' | 'page-fetch';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'agents-docs-stale' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return' | 'channel-collision' | 'channel-instance-authorize' | 'dotenv-node-env' | 'page-fetch' | 'i18n-layout' | 'i18n-app-scope';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -25,6 +25,8 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkI18nLayout } from './doctor/i18n-layout.js';
+export { checkI18nAppScope } from './doctor/i18n-app-scope.js';
 export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { checkChannelInstanceAuthorize, declaresInstance, hasAuthorize, } from './doctor/channel-instance-authorize.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
@@ -33,7 +35,7 @@ export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, }
  * 실행할 검사 이름. 지정 없음(undefined) = 31개 모두.
  */
 /**
- * doctor 정적 검사 33종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 35종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */

package/dist/doctor.js

@@ -30,6 +30,8 @@
  * 25) schema-relations (§4.5 · 결정 134 · 커넥션 가로지르는 belongsTo·관계 · 대상 부재 error)
  * 26) no-import-meta-env (결정 198 · F-9 ② · `.vue` 의 import.meta.env = TS1470 → env 접근자 안내 error)
  * 27) locale-parity (결정 216 · 13차 W4 · 로케일 간 키 부분 누락 = fallback 조용 노출 경고)
+ * 34) i18n-layout (결정 454 · 레거시 단일 파일 = 클라 t() 불가 안내 · --fix 로 폴더 이관)
+ * 35) i18n-app-scope (결정 454 · 앱 카탈로그에 없는 클라 t() 키 = 런타임 키 노출)
  * 28) render-return (결정 340 · this.render/redirect/json 호출만 하고 return 누락 = 무신호 204 경고)
  * 29) channel-collision (§7 · 앱간 동명 채널 = 전역 subject·프레즌스 병합 error)
  * 30) channel-instance-authorize (결정 440 · authorize 없는 인스턴스 채널 = 임의 인스턴스 공개 입장 경고)
@@ -76,6 +78,8 @@ import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { checkLinkButtonNesting } from './doctor/link-button-nesting.js';
 import { checkNoImportMetaEnv } from './doctor/no-import-meta-env.js';
 import { checkLocaleParity } from './doctor/locale-parity.js';
+import { checkI18nLayout } from './doctor/i18n-layout.js';
+import { checkI18nAppScope } from './doctor/i18n-app-scope.js';
 import { checkChannelCollision } from './doctor/channel-collision.js';
 import { checkChannelInstanceAuthorize } from './doctor/channel-instance-authorize.js';
 import { checkDotenvNodeEnv } from './doctor/dotenv-node-env.js';
@@ -108,6 +112,8 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkI18nLayout } from './doctor/i18n-layout.js';
+export { checkI18nAppScope } from './doctor/i18n-app-scope.js';
 export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { checkChannelInstanceAuthorize, declaresInstance, hasAuthorize, } from './doctor/channel-instance-authorize.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
@@ -116,7 +122,7 @@ export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, }
  * 실행할 검사 이름. 지정 없음(undefined) = 31개 모두.
  */
 /**
- * doctor 정적 검사 33종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 35종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -154,6 +160,8 @@ export const ALL_RULES = [
     'channel-instance-authorize',
     'dotenv-node-env',
     'page-fetch',
+    'i18n-layout',
+    'i18n-app-scope',
 ];
 /**
  * `gaon help` 이 doctor 한 줄에 요약할 규칙별 문구(§2.2 상세는 AGENTS). 타입이
@@ -190,6 +198,8 @@ export const RULE_SUMMARIES = {
     'schema-relations': '§4.5 관계',
     'no-import-meta-env': 'import.meta.env',
     'locale-parity': '로케일 커버리지',
+    'i18n-layout': 'i18n 카탈로그 레이아웃(단일 파일 → backend/frontend 분리 안내 · 결정 454)',
+    'i18n-app-scope': '앱 경계를 넘는 클라 번역 키(그 앱 카탈로그에 없는 t() 키 · 결정 454)',
     'render-return': 'render return 누락',
     'channel-collision': '앱간 동명 채널',
     'channel-instance-authorize': '인스턴스 채널 authorize',
@@ -225,6 +235,8 @@ const CHECKERS = {
     'schema-relations': checkSchemaRelations,
     'no-import-meta-env': checkNoImportMetaEnv,
     'locale-parity': checkLocaleParity,
+    'i18n-layout': checkI18nLayout,
+    'i18n-app-scope': checkI18nAppScope,
     'render-return': checkRenderReturn,
     'channel-collision': checkChannelCollision,
     'channel-instance-authorize': checkChannelInstanceAuthorize,

package/dist/index.js

@@ -156,7 +156,7 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 33종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 35종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
@@ -177,7 +177,7 @@ export function parseDoctorChecks(argv) {
     }
     // 결정 411: 모르는 이름은 여전히 무시하되(안전 방향 — 전체 검사로 넓어짐) **조용히**
     // 넘기지 않는다. 오타 하나가 "그 검사만 돌렸다" 는 착각으로 이어지고, 전부 오타면
-    // 33종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
+    // 35종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
     if (unknown.length > 0) {
         process.stderr.write(`  ! 알 수 없는 검사 이름 무시: ${unknown.join(", ")}\n` +
             `    → 지원 이름은 gaon doctor --json 의 rule 값 또는 gaon help 참고` +