# 前端国际化-核心模块会话记录 ## 元数据 - 需求编号：2026-01-26-002-02 - 开始时间：2026-01-26 - 结束时间：2026-01-26 - 当前阶段：阶段 7：记录当前会话 - 状态：已完成 ## 阶段 1：需求定义与入库 ### 需求分析 - 需求概述：在基础架构完成后，对系统的核心公共模块进行国际化改造，包括布局组件、认证页面及全局公共提示，确保用户进入系统的第一眼体验是本地化的。 - 功能需求： - 布局（Layout）国际化：侧边栏菜单、顶部导航、标签页 - 认证模块（Auth）国际化：登录页、注册页 - 全局公共文本：HTTP 错误处理、错误码字典 - 技术约束： - 基于 Vue 3 + Element Plus - 使用 vue-i18n@9（已在阶段 1 完成基础架构） - 遵循项目现有的代码规范和组件结构 - 成功标准： - 登录页、注册页的所有中文提示均已替换为 `t('key')` - 导航栏下拉菜单、退出提示框均已国际化 - 模拟 401/404 错误，提示信息正确显示对应语言的文本 - `errorCode.ts` 改造完成，且在拦截器中正确翻译 ### 创建需求文档 - 路径：`docs/requirements/2026-01-26-002-02-前端国际化-核心模块.md` - 状态：已完成 ### 更新索引 - 在 `docs/index.md` 中添加需求文档链接 ## 阶段 2：方案设计 ### 需求分析 - 分析需求的技术要求： - 功能需求：布局国际化、认证模块国际化、全局公共文本国际化 - 技术约束：Vue 3 + Element Plus + vue-i18n@9 - 成功标准：所有中文提示替换为 `t('key')`，错误提示正确显示对应语言 - 确定技术栈和架构方案： - 前端层：Vue 3 Composition API、Element Plus UI 组件库、vue-i18n@9 国际化库、Pinia 状态管理 - 国际化方案：基于 vue-i18n 的 Composition API，使用 `useI18n` 获取翻译函数，约定路由 Title 必须为 Translation Key，错误码字典使用 Translation Key - 识别关键设计决策点： - 决策点 1：侧边栏菜单国际化 - 是否需要动态更新菜单标题？如何处理路由 Title 为普通文本的情况？ - 决策点 2：标签页国际化 - `visitedViews` 中的 title 是否需要动态更新？是否需要监听语言切换事件？ - 决策点 3：错误码字典国际化 - 是否将 Value 修改为 Translation Key？如何在拦截器中正确翻译错误码？ - 决策点 4：表单验证规则国际化 - 如何在 Element Plus 的表单验证中使用国际化？是否需要自定义验证规则？ ### 架构设计 - 系统架构设计： - Layout 布局模块：负责侧边栏菜单、顶部导航、标签页的国际化 - Auth 认证模块：负责登录页、注册页的国际化 - Common 公共模块：负责 HTTP 错误处理、错误码字典的国际化 - vue-i18n 国际化引擎：提供语言切换和文本翻译功能 - Pinia 状态管理：管理语言状态和语言切换方法 - 模块架构设计： - 涉及的文件和组件： - `src/layout/components/Sidebar/SidebarItem.vue` - 侧边栏菜单项（需改造） - `src/layout/components/Navbar/index.vue` - 顶部导航（需改造） - `src/layout/components/TagsView/index.vue` - 标签页（需改造） - `src/views/auth/login.vue` - 登录页（需改造） - `src/views/auth/register.vue` - 注册页（需改造） - `src/utils/request.ts` - HTTP 请求拦截器（需改造） - `src/utils/errorCode.ts` - 错误码字典（需改造） - `src/locales/zh-CN.ts` - 中文翻译（需扩展） - `src/locales/en-US.ts` - 英文翻译（需扩展） - 数据流设计： - 语言切换数据流：用户点击语言切换按钮 -> 调用 LangSelect 组件的 handleLanguageChange 方法 -> 调用 appStore.setLanguage(languageCode) -> Pinia 更新 language 状态 -> 触发 vue-i18n 的 locale 变化 -> 所有使用 t('key') 的组件重新渲染 -> 显示对应语言的文本 - 错误处理数据流：HTTP 请求失败 -> request.ts 拦截器捕获错误 -> 根据错误码从 errorCode.ts 获取错误信息 -> 调用 i18n.global.t(errorKey) 翻译错误信息 -> 显示翻译后的错误提示 ### 技术方案设计 - 技术选型： - vue-i18n@9：Vue 3 官方推荐的国际化库，与 Vue 3 完美兼容，支持 Composition API，性能优秀 - Pinia：Vue 3 官方推荐的状态管理库，与 vue-i18n 集成良好 - Element Plus：项目已使用，支持国际化配置 - 核心算法设计： - 算法 1：侧边栏菜单标题翻译 - 检查 route.meta.title 是否存在，使用 i18n.global.t(route.meta.title) 翻译，如果翻译结果与原文本相同，显示原文本 - 算法 2：错误码翻译 - 从 errorCode.ts 获取错误信息（Translation Key），使用 i18n.global.t(errorKey) 翻译错误信息，如果翻译结果与原 Key 相同，显示默认错误信息 - 集成方案设计： - 与 vue-i18n 集成：在组件中使用 `useI18n()` 获取翻译函数，在模板中使用 `{{ $t('key') }}` 或 `{{ t('key') }}`，在 JavaScript 中使用 `i18n.global.t('key')` - 与 Element Plus 集成：使用 `ElConfigProvider` 配置 Element Plus 的语言，监听语言变化，动态更新 Element Plus 的语言配置 - 与 Pinia 集成：在 appStore 中管理语言状态，提供 `setLanguage` 方法切换语言，持久化语言设置到 localStorage ### 数据模型设计 - 翻译资源文件数据结构： - zh-CN.ts：包含 common、layout、login、register、error 等模块的中文翻译 - en-US.ts：包含 common、layout、login、register、error 等模块的英文翻译 - 错误码字典数据结构： - errorCode.ts：错误码的 Value 改为 Translation Key，在 request.ts 中使用 `i18n.global.t(msg)` 翻译错误信息 - 路由配置数据结构： - 路由的 `meta.title` 必须为 Translation Key，使用三层结构：`module.submodule.key` ### 接口设计 - 侧边栏菜单接口：SidebarItemProps、SidebarItemEmits、SidebarItemMethods - 顶部导航接口：NavbarProps、NavbarEmits、NavbarMethods - 登录页接口：LoginProps、LoginEmits、LoginCredentials、LoginMethods、LoginRules - 注册页接口：RegisterProps、RegisterEmits、RegisterCredentials、RegisterMethods、RegisterRules - 错误处理接口：RequestInterceptor、ErrorResponse、ErrorInterceptorMethods、ErrorCode ### 实现要点设计 - 关键实现逻辑： - 侧边栏菜单标题翻译：使用 `useI18n()` 获取翻译函数，实现 `getTitle` 和 `hasTitle` 方法 - 顶部导航国际化：使用 `ElMessageBox.confirm` 显示退出确认框，所有文本使用翻译函数 - 登录页表单验证国际化：表单验证规则的 `message` 使用 Translation Key - 注册页变量插值：使用 `t('register.tips.success', { username })` 支持变量插值 - 错误码翻译：在拦截器中调用 `translateError(code)` 翻译错误信息 - 异常处理设计： - 翻译 Key 不存在：实现 `safeTranslate` 函数，回退到原始文本或默认文本 - 路由 Title 为空：检查 title 是否存在，不存在返回空字符串 - 错误码不存在：使用默认错误码，回退到默认错误信息 - 性能优化设计： - 翻译缓存：使用 vue-i18n 的内置缓存机制 - 懒加载翻译资源：按需加载翻译资源 - 避免不必要的重新渲染：使用 computed 缓存翻译结果 - 安全设计： - 防止 XSS 攻击：vue-i18n 默认会对翻译结果进行 HTML 转义 - 防止 SQL 注入：前端国际化不涉及数据库操作，无需特别处理 - 防止 CSRF 攻击：前端国际化不涉及表单提交，无需特别处理 - 测试要点： - 语言切换测试：测试语言切换是否正确更新所有翻译 - 翻译 Key 不存在测试：测试翻译 Key 不存在时的回退逻辑 - 变量插值测试：测试变量插值是否正确 ### 创建设计文档 - 路径：`docs/design/2026-01-26-002-02-前端国际化-核心模块-设计.md` - 内容： - 元数据：需求编号、创建时间、状态 - 设计概述：基于 vue-i18n@9 和 Vue 3 Composition API，对系统的核心公共模块进行国际化改造 - 架构设计：系统架构图、模块架构图、数据流图 - 技术方案：技术选型、核心算法、集成方案 - 数据模型：翻译资源文件数据结构、错误码字典数据结构、路由配置数据结构 - 接口设计：侧边栏菜单接口、顶部导航接口、登录页接口、注册页接口、错误处理接口 - 实现要点：关键实现逻辑、异常处理、性能优化、安全设计、测试要点 - 相关文档：需求文档、父需求文档、决策记录 ### 更新索引和需求文档 - 更新索引：在 `docs/index.md` 中添加设计文档链接 - 更新需求文档：在需求文档的"相关文档"部分添加设计文档引用 ### 更新会话记录 - 更新阶段 2 信息： - 更新"当前阶段"为"阶段 2：方案设计" - 更新"阶段 2：方案设计"的状态为"已完成" - 添加生成文档链接 - 添加关键设计决策 ### 生成的文档 - [设计文档](../design/2026-01-26-002-02-前端国际化-核心模块-设计.md) ### 更新的文档 - [docs/index.md](../index.md) - 添加了设计文档链接 - [需求文档](../requirements/2026-01-26-002-02-前端国际化-核心模块.md) - 添加了设计文档引用 - [会话记录](./2026-01-26-002-02-session.md) - 更新了阶段 2 信息 ## 阶段 3：方案决策 - 状态：已完成 - 生成文档：[2026-01-26-002-02-ADR-前端国际化-核心模块实现策略决策](../decisions/2026-01-26-002-02-ADR-前端国际化-核心模块实现策略决策.md) ### 决策分析 - 识别关键决策点： - 决策点 1：侧边栏菜单标题翻译策略 - 静态翻译 vs 动态翻译 - 决策点 2：标签页标题更新策略 - 监听语言切换事件 vs 不监听 - 决策点 3：错误码字典改造策略 - Value 改为 Translation Key vs 保持普通文本 - 决策点 4：表单验证规则国际化策略 - message 使用 Translation Key vs 自定义验证函数 - 分析至少两种技术方案的优缺点： - 决策点 1：静态翻译（代码简洁、性能好、统一规范）vs 动态翻译（兼容性好、灵活性高） - 决策点 2：监听语言切换事件（用户体验好、一致性好）vs 不监听（实现简单、性能好） - 决策点 3：错误码 Value 改为 Translation Key（符合最佳实践、代码简洁）vs 保持普通文本（兼容性好、灵活性高） - 决策点 4：表单验证规则 message 使用 Translation Key（符合最佳实践、代码简洁）vs 自定义验证函数（灵活性高、支持复杂逻辑） - 确定最终决策和理由： - 决策点 1：选择静态翻译（约定路由 Title 必须为 Translation Key）- 符合国际化最佳实践，代码简洁易维护，性能优秀 - 决策点 2：选择监听语言切换事件，动态更新标签页标题 - 用户体验优先，一致性，虽然实现复杂但值得 - 决策点 3：选择错误码 Value 改为 Translation Key - 符合国际化最佳实践，代码简洁易维护，易于扩展 - 决策点 4：选择表单验证规则的 message 使用 Translation Key - 符合国际化最佳实践，代码简洁易维护，易于扩展 ### 强制校验 - 搜索已有 ADR 记录： - 查找结果：[2026-01-26-002-01-ADR-前端国际化技术选型与架构决策](../decisions/2026-01-26-002-01-ADR-前端国际化技术选型与架构决策.md) - 冲突检查：没有冲突，已有的 ADR 记录是关于前端国际化技术选型与架构决策，当前的决策是关于前端国际化-核心模块的具体实现策略 - 确认决策的一致性： - 确认决策与项目规则一致 - 确认决策与 SSOT 架构师提示词一致 - 确认决策与需求文档一致 ### 创建决策记录 - 路径：`docs/decisions/2026-01-26-002-02-ADR-前端国际化-核心模块实现策略决策.md` - 内容： - 标题：ADR-002: 前端国际化-核心模块实现策略决策 - 状态：已接受 - 日期：2026-01-26 - 背景：前端国际化-核心模块需要确定具体的实现策略 - 决策： - 决策 1：侧边栏菜单标题翻译策略 - 静态翻译（约定路由 Title 必须为 Translation Key） - 决策 2：标签页标题更新策略 - 监听语言切换事件，动态更新标签页标题 - 决策 3：错误码字典改造策略 - 错误码 Value 改为 Translation Key - 决策 4：表单验证规则国际化策略 - 表单验证规则的 message 使用 Translation Key - 后果： - 正面影响：符合国际化最佳实践、代码简洁易维护、性能优秀、统一规范、用户体验好、易于扩展 - 负面影响：初期工作量、需要确保所有文本都有对应的翻译、标签页动态更新需要额外处理 - 替代方案：列出所有考虑过的方案 - 相关文档：需求文档、设计文档、ADR-001 ### 更新索引和设计文档 - 更新索引：在 `docs/index.md` 中添加决策记录链接 - 更新设计文档：在设计文档的"相关文档"部分添加决策记录引用 ### 更新会话记录 - 更新阶段 3 信息： - 更新"当前阶段"为"阶段 3：方案决策" - 更新"阶段 3：方案决策"的状态为"已完成" - 添加生成文档链接 - 添加关键决策内容 ### 生成的文档 - [决策记录](../decisions/2026-01-26-002-02-ADR-前端国际化-核心模块实现策略决策.md) ### 更新的文档 - [docs/index.md](../index.md) - 添加了决策记录链接 - [设计文档](../design/2026-01-26-002-02-前端国际化-核心模块-设计.md) - 添加了决策记录引用 - [会话记录](./2026-01-26-002-02-session.md) - 更新了阶段 3 信息 ## 阶段 4：数据库结构生成 - 状态：不适用（本需求不涉及数据库变更） - 生成文档：无 - 关键决策：无 ### 需求分析 - 分析需求是否涉及数据库变更： - 读取设计文档：[2026-01-26-002-02-前端国际化-核心模块-设计](../design/2026-01-26-002-02-前端国际化-核心模块-设计.md) - 检查数据模型部分： - 翻译资源文件数据结构：`zh-CN.ts` 和 `en-US.ts`（前端 TypeScript 文件） - 错误码字典数据结构：`errorCode.ts`（前端 TypeScript 文件） - 路由配置数据结构：路由配置（前端配置文件） - 检查是否需要创建新表：否 - 检查是否需要修改现有表：否 - 检查是否需要添加索引：否 - 检查是否需要插入初始数据：否 - 分析结论： - **不涉及数据库变更** - 所有变更都是前端层面的改造 - 不需要创建新表 - 不需要修改现有表 - 不需要添加索引 - 不需要插入初始数据 ### 跳过此阶段 - 根据分析结果，本需求不涉及数据库变更，因此跳过阶段 4，直接进入阶段 5（提示词生成） ### 更新会话记录 - 更新阶段 4 信息： - 更新"当前阶段"为"阶段 4：数据库结构生成" - 更新"阶段 4：数据库结构生成"的状态为"不适用" - 记录是否涉及数据库变更：不涉及 - 记录分析过程 ### 更新的文档 - [会话记录](./2026-01-26-002-02-session.md) - 更新了阶段 4 信息 ## 阶段 5：提示词生成 - 状态：已完成 - 生成文档：[2026-01-26-002-02-prompt-前端国际化-核心模块](../prompts/2026-01-26-002-02-prompt-前端国际化-核心模块.md) - 关键决策：无 ### 提示词分析 - 分析需求的核心任务： - 读取需求文档：[2026-01-26-002-02-前端国际化-核心模块](../requirements/2026-01-26-002-02-前端国际化-核心模块.md) - 读取设计文档：[2026-01-26-002-02-前端国际化-核心模块-设计](../design/2026-01-26-002-02-前端国际化-核心模块-设计.md) - 识别需求的核心功能和非功能需求 - 确定需要生成的代码类型：前端 Vue 组件改造、前端 TypeScript 文件扩展、前端工具函数实现 - 确定需要生成的提示词类型： - 提示词类型：前端改造提示词 - 涉及技术：Vue 组件改造、TypeScript 文件扩展、工具函数实现、翻译资源文件扩展 - 设计提示词的结构和内容： - 引用真源（需求文档和设计文档） - 需求描述 - 设计方案 - 输出格式要求 - 代码规范要求 - 测试要求 - 注意事项 ### 提示词生成 - 确定文档路径：`docs/prompts/2026-01-26-002-02-prompt-前端国际化-核心模块.md` - 填充提示词内容： - 引用真源：需求文档、设计文档、决策记录 - 需求描述：布局国际化、认证模块国际化、全局公共文本国际化 - 设计方案：侧边栏菜单标题翻译策略、标签页标题更新策略、错误码字典改造策略、表单验证规则国际化策略 - 输出格式要求：必须包含的文件、必须包含单元测试、必须符合 Vue 3 最佳实践、必须遵循项目现有代码规范 - 代码规范要求：组件命名、方法命名、变量命名、注释规范、代码格式、导入规范 - 测试要求：单元测试覆盖率不低于 80%、测试用例包含的场景、使用 Vitest 进行测试、测试用例命名规范、测试数据使用 mock 模拟 - 注意事项：必须使用 vue-i18n 的 Composition API、必须遵循决策记录的决策、必须处理异常情况、必须优化性能、必须确保安全性、必须遵循 Element Plus 国际化规范、必须与 Pinia 状态管理集成 ### 提示词质量检查 - 提示词已创建在 `docs/prompts/` 目录下 - 提示词命名符合 `YYYY-MM-DD-00X-prompt-提示词名.md` 格式 - 提示词包含引用真源（需求文档、设计文档、决策记录的链接） - 提示词包含需求描述 - 提示词包含设计方案 - 提示词包含输出格式要求 - 提示词包含代码规范要求 - 提示词包含测试要求 - 提示词包含注意事项 ### 更新索引和需求文档 - 更新 `docs/index.md`： - 在"提示词"部分追加新提示词 - 格式：`- [2026-01-26-002-02-prompt-前端国际化-核心模块](./prompts/2026-01-26-002-02-prompt-前端国际化-核心模块.md) - 前端国际化核心模块的执行提示词` - 更新需求文档： - 在"相关文档"部分添加提示词引用 - 格式：`- [提示词文档](../prompts/2026-01-26-002-02-prompt-前端国际化-核心模块.md)` ### 更新的文档 - [docs/index.md](../index.md) - 添加了提示词链接 - [需求文档](../requirements/2026-01-26-002-02-前端国际化-核心模块.md) - 添加了提示词引用 - [会话记录](./2026-01-26-002-02-session.md) - 更新了阶段 5 信息 ## 阶段 6：执行代码生成 - 状态：已完成 - 生成文档：无 - 关键决策：无 ### 代码生成分析 - 分析需求和设计文档： - 读取需求文档：[2026-01-26-002-02-前端国际化-核心模块](../requirements/2026-01-26-002-02-前端国际化-核心模块.md) - 读取设计文档：[2026-01-26-002-02-前端国际化-核心模块-设计](../design/2026-01-26-002-02-前端国际化-核心模块-设计.md) - 读取决策记录：[2026-01-26-002-02-ADR-前端国际化-核心模块实现策略决策](../decisions/2026-01-26-002-02-ADR-前端国际化-核心模块实现策略决策.md) - 读取提示词：[2026-01-26-002-02-prompt-前端国际化-核心模块](../prompts/2026-01-26-002-02-prompt-前端国际化-核心模块.md) - 明确需求的核心功能和非功能需求： - 布局（Layout）国际化：侧边栏菜单、顶部导航、标签页 - 认证模块（Auth）国际化：登录页、注册页 - 全局公共文本国际化：HTTP 错误处理、错误码字典 - 明确设计的技术方案和架构： - 侧边栏菜单标题翻译策略：静态翻译（约定路由 Title 必须为 Translation Key） - 标签页标题更新策略：监听语言切换事件，动态更新标签页标题 - 错误码字典改造策略：错误码 Value 改为 Translation Key - 表单验证规则国际化策略：表单验证规则的 `message` 使用 Translation Key ### 确定需要生成的代码文件 - 翻译资源文件： - `src/locales/zh-CN.ts`：中文翻译文件 - `src/locales/en-US.ts`：英文翻译文件 - 布局组件： - `src/layout/components/Sidebar/SidebarItem.vue`：侧边栏菜单项 - `src/layout/components/Navbar/index.vue`：顶部导航 - `src/layout/components/TagsView/index.vue`：标签页 - 认证模块： - `src/views/auth/login.vue`：登录页 - `src/views/auth/register.vue`：注册页 - 公共模块： - `src/utils/request.ts`：HTTP 请求拦截器 - `src/utils/errorCode.ts`：错误码字典 - 单元测试： - `src/locales/__tests__/zh-CN.test.ts`：中文翻译测试 - `src/locales/__tests__/en-US.test.ts`：英文翻译测试 ### 代码生成过程 - 步骤 1：生成/更新翻译资源文件 - 更新 `src/locales/zh-CN.ts`：添加布局、认证、错误等翻译 - 更新 `src/locales/en-US.ts`：添加布局、认证、错误等翻译 - 步骤 2：更新布局组件 - 更新 `src/layout/components/Sidebar/SidebarItem.vue`：添加 `translateTitle` 方法，使用 `useI18n()` 获取翻译函数 - 更新 `src/layout/components/Navbar/index.vue`：添加国际化支持，使用 `t()` 函数翻译文本 - 更新 `src/layout/components/TagsView/index.vue`：添加 `getTagTitle` 和 `updateAllTagsTitle` 方法，监听语言切换事件 - 步骤 3：更新认证模块 - 更新 `src/views/auth/login.vue`：添加 `useI18n()`，使用 `t()` 函数翻译表单验证规则和提示信息 - 更新 `src/views/auth/register.vue`：添加 `useI18n()`，使用 `t()` 函数翻译表单验证规则和提示信息 - 步骤 4：更新公共模块 - 更新 `src/utils/errorCode.ts`：将错误码 Value 改为 Translation Key - 更新 `src/utils/request.ts`：添加 `useI18n()`，在拦截器中使用 `t()` 函数翻译错误信息 - 步骤 5：生成单元测试 - 创建 `src/locales/__tests__/zh-CN.test.ts`：测试中文翻译文件 - 创建 `src/locales/__tests__/en-US.test.ts`：测试英文翻译文件 ### 生成的代码文件列表 - `src/locales/zh-CN.ts`：中文翻译文件（已更新） - `src/locales/en-US.ts`：英文翻译文件（已更新） - `src/layout/components/Sidebar/SidebarItem.vue`：侧边栏菜单项（已更新） - `src/layout/components/Navbar/index.vue`：顶部导航（已更新） - `src/layout/components/TagsView/index.vue`：标签页（已更新） - `src/views/auth/login.vue`：登录页（已更新） - `src/views/auth/register.vue`：注册页（已更新） - `src/utils/request.ts`：HTTP 请求拦截器（已更新） - `src/utils/errorCode.ts`：错误码字典（已更新） - `src/locales/__tests__/zh-CN.test.ts`：中文翻译测试（已创建） - `src/locales/__tests__/en-US.test.ts`：英文翻译测试（已创建） ### 代码质量检查 - 代码符合 Vue 3 最佳实践： - 使用 Composition API - 使用 `