From 2ec6f6c4baa155197ff9b493b4b8c391c45e4a7e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=B8=A5=E6=B5=A9?= <h_mini2024@oo1.dev>
Date: Sun, 26 Oct 2025 21:28:25 +0800
Subject: [PATCH] =?UTF-8?q?docs(locales-4-route):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E8=B7=AF=E7=94=B1=E6=A0=87=E9=A2=98=E5=9B=BD=E9=99=85=E5=8C=96?=
 =?UTF-8?q?=E6=9C=BA=E5=88=B6=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/locales-4-route/README.md                 | 66 +++++++++++++++++++
 src/locales-4-route/_messages-auto-imports.ts |  1 +
 src/locales-4-route/en-US.ts                  |  2 +-
 src/locales-4-route/zh-CN.ts                  |  2 +-
 src/pages/Home.page.vue                       |  7 +-
 5 files changed, 70 insertions(+), 8 deletions(-)
 create mode 100644 src/locales-4-route/README.md

diff --git a/src/locales-4-route/README.md b/src/locales-4-route/README.md
new file mode 100644
index 0000000..a4d28dc
--- /dev/null
+++ b/src/locales-4-route/README.md
@@ -0,0 +1,66 @@
+# `locales-4-route`
+
+此目录存放专门用于**路由名称**的国际化（i18n）消息。这些消息通过一套自定义的编译时安全机制，为应用的导航菜单提供标题。
+
+## 解决什么问题？
+
+`unplugin-vue-router` 的 `definePage()` 宏在编译时执行，无法访问 Vue `<script setup>` 作用域中的运行时变量（如 `t()` 函数）。这使得在路由元信息（`meta`）中直接定义多语言标题变得不可能。
+
+## 解决方案：自定义的编译时安全机制
+
+我们采用一种**约定优于配置**的策略，并利用 TypeScript 进行编译时检查，以确保所有菜单标题都已定义。
+
+**工作流程：**
+
+1.  **`RouteNamedMap` 的生成**：`unplugin-vue-router` 会扫描你的页面组件，并自动生成一个名为 `RouteNamedMap` 的 TypeScript 类型，该类型包含了项目中所有具名路由的 `name`。
+
+2.  **自定义全局类型**：我们定义了一个全局类型 `PageTitleLocalizations`：
+
+    ```typescript
+    declare global {
+      type PageTitleLocalizations = Record<keyof RouteNamedMap, string>;
+    }
+    ```
+
+    这个自定义类型创建了一个**契约**：任何满足此类型的对象，都**必须**为 `RouteNamedMap` 中的每一个路由名称提供一个字符串类型的键值对。
+
+3.  **编译时检查**：此目录下的每个语言环境文件（如 `en-US.ts`）都必须使用 `satisfies PageTitleLocalizations` 来进行类型断言。
+
+    ```typescript
+    // src/locales-4-route/en-US.ts
+    export default { ... } satisfies PageTitleLocalizations;
+    ```
+
+    这个操作会触发 TypeScript 在**编译时**进行检查。如果你新增了一个具名路由但忘记在此处添加翻译，**TypeScript 编译将会失败**，并明确提示你缺少的键。
+
+4.  **菜单生成**：在运行时，`@/composables/useMetaLayoutsMenuOptions.tsx` 会获取当前路由的 `name`，并使用它作为键（`t(routeName)`）来查找并显示菜单标题。由于有编译时检查，我们可以确信翻译始终存在。
+
+### 带来的好处
+
+- **杜绝遗漏**：从根本上解决了菜单项标题缺失或显示为原始键的问题。
+- **关注点分离**：路由定义只关心路由结构，显示文本则集中在此处管理。
+
+### 开发者实践指南
+
+1.  **理解路由命名规则**：
+    `unplugin-vue-router` 会根据页面组件的**文件路径**自动生成 `PascalCase` 格式的路由 `name`。
+    - **示例**：
+      - 文件路径：`src/pages/demos/api-demo.page.vue`
+      - 自动生成的路由 `name`：`DemosApiDemo`
+
+2.  **添加对应的翻译**：
+    使用上一步中自动生成的 `name` 作为键，在此目录的每个语言文件中添加翻译。
+
+    ```ts
+    // src/locales-4-route/zh-CN.ts
+    export default {
+      // ... 其他翻译
+      DemosApiDemo: 'API 演示',
+    } satisfies PageTitleLocalizations;
+
+    // src/locales-4-route/en-US.ts
+    export default {
+      // ... 其他翻译
+      DemosApiDemo: 'API Demo',
+    } satisfies PageTitleLocalizations;
+    ```
diff --git a/src/locales-4-route/_messages-auto-imports.ts b/src/locales-4-route/_messages-auto-imports.ts
index 621dd10..bdd2024 100644
--- a/src/locales-4-route/_messages-auto-imports.ts
+++ b/src/locales-4-route/_messages-auto-imports.ts
@@ -6,6 +6,7 @@ const modules = import.meta.glob(['./*.ts', '!./_messages-auto-imports.ts'], {
 });
 
 type MessageType = Record<string, string>;
+
 export const locales4RouteMessages: I18nOptions['messages'] = Object.entries(modules).reduce(
   (messages, [path, mod]) => {
     const locale = path.replace(/(\.\/|\.ts)/g, '');
diff --git a/src/locales-4-route/en-US.ts b/src/locales-4-route/en-US.ts
index 22b5032..ff98d80 100644
--- a/src/locales-4-route/en-US.ts
+++ b/src/locales-4-route/en-US.ts
@@ -7,4 +7,4 @@ export default {
   DemosI18nDemo: 'i18n Demo',
   DemosWebsocketDemo: 'WebSocket Demo',
   Home: 'Home',
-} satisfies PageTitleLocalizations;
+} as const satisfies PageTitleLocalizations;
diff --git a/src/locales-4-route/zh-CN.ts b/src/locales-4-route/zh-CN.ts
index 10685b0..dab28a4 100644
--- a/src/locales-4-route/zh-CN.ts
+++ b/src/locales-4-route/zh-CN.ts
@@ -7,4 +7,4 @@ export default {
   DemosI18nDemo: '国际化示例',
   DemosWebsocketDemo: 'WebSocket 示例',
   Home: '首页',
-} satisfies PageTitleLocalizations;
+} as const satisfies PageTitleLocalizations;
diff --git a/src/pages/Home.page.vue b/src/pages/Home.page.vue
index 5e72909..91af4a2 100644
--- a/src/pages/Home.page.vue
+++ b/src/pages/Home.page.vue
@@ -1,10 +1,5 @@
 <script setup lang="ts">
-definePage({
-  meta: {
-    title: '首页',
-    hideInMenu: false,
-  },
-});
+definePage({ meta: { hideInMenu: false } });
 </script>
 
 <template>