@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/templates/shared/rules/fec-design-system.md

@@ -1,72 +1,72 @@
-# 设计系统规则
+# Design system rules
 
-凡是任务涉及 UI 实现、设计稿转代码、样式、设计 Token 或组件复用时，都应用本文件。本文只保留项目常驻设计约束；产品化设计方向、设计系统生成、页面级 override、UI QA 细节交给 `fec-ui-design`；Tailwind token、variant、dark mode 和 class 治理交给 `fec-tailwind-design-system`；响应式布局交给 `fec-responsive-layout`。
+This document should be used whenever the task involves UI implementation, design draft conversion to code, style, design token, or component reuse. This article only retains the project's resident design constraints; product design direction, design system generation, page-level override, and UI QA details are handed over to `fec-ui-design`; Tailwind token, variant, dark mode and class management are handed over to `fec-tailwind-design-system`; responsive layout is handed over to `fec-responsive-layout`.
 
-## 核心优先级
+## Core priority
 
-1. 复用已有组件。
-2. 在已有组件上扩展。
-3. 创建新的叶子组件。
-4. 只有在理由充分、边界清晰且会被复用时，才创建新的共享基础组件。
+1. Reuse existing components.
+2. Expand on existing components.
+3. Create a new leaf component.
+4. Only create new shared base components if there is good reason, clear boundaries, and if they will be reused.
 
-## 产品化设计方向
+## Product design direction
 
-- 工具型页面、SaaS 后台、CRM、运营台：优先安静、密集、可扫描，首屏直接呈现核心工作区。
-- 品牌页、作品集、发布页：可以更有表现力，但 H1 应是品牌、产品、对象或品类，说明文案放在副标题。
-- 可视化、游戏、创作工具：可以使用更强视觉资产和动效，但必须保持交互可控、状态清晰。
-- 每个重要界面都应有贴合业务的视觉锚点，例如真实媒体、数据形态、行业材质、字体性格、空间组织或交互节奏。
-- 大胆设计必须服务场景；高频工具重效率和稳定，展示型页面重主体识别和记忆点。
+- Tool-type pages, SaaS backend, CRM, and operations desk: Prioritize quiet, dense, and scannable, and the core work area is directly displayed on the first screen.
+- Brand page, portfolio, release page: It can be more expressive, but H1 should be the brand, product, object or category, and the description copy should be placed in the subtitle.
+- Visualization, games, and creative tools: You can use stronger visual assets and animations, but you must keep the interaction controllable and the status clear.
+- Every important interface should have a visual anchor that fits the business, such as real media, data form, industry material, font character, spatial organization or interaction rhythm.
+- Bold design must serve the scene; high-frequency tools focus on efficiency and stability, and display-type pages focus on subject recognition and memory points.
 
-避免：
+Avoid:
 
-- 把日常高频工具做成营销落地页。
-- 默认使用紫色渐变、装饰光斑、堆叠卡片、空泛 hero 或无语境默认字体。
-- 页面区块大面积卡片化，尤其是卡片套卡片。
-- 用可见说明文字解释常见控件本该表达的功能。
-- 让整个界面只由一个色相的深浅变化组成。
+- Turn daily high-frequency tools into marketing landing pages.
+- Use purple gradient, decorative light spots, stacked cards, empty hero or non-contextual default font by default.
+- Large areas of the page are card-based, especially card sets.
+- Use visible explanatory text to explain the functions that common controls are supposed to express.
+- Let the entire interface consist of only one shade of hue.
 
-## 设计稿转代码规则
+## Design draft conversion code rules
 
-- 有设计上下文时，先通过 MCP 或截图/标注读取事实来源，不靠猜测决定布局、间距、字体、颜色或状态。
-- 设计稿中的颜色、间距、圆角、阴影和字体应映射到现有 token、CSS 变量、主题变量或组件 variant。
-- 创建新组件前先检查现有组件库和业务组件，优先复用。
-- 默认验证 mobile(375px)、tablet(768px)、desktop(1440px)。
-- 像素还原要求以项目约定为准；没有约定时，核心结构、间距、字体、状态和交互优先于机械追求截图重合。
-- 复杂设计任务实现前先给出简短实现计划，说明复用组件、新建组件、可能改动文件、响应式策略和 token 映射。
+- When given design context, read the source of truth first through MCP or screenshots/annotations, and don’t rely on guesswork to determine layout, spacing, fonts, colors, or status.
+- Colors, spacing, rounded corners, shadows, and fonts in the design should be mapped to existing tokens, CSS variables, theme variables, or component variants.
+- Check existing component libraries and business components before creating new components and prioritize reuse.
+- Default verification is mobile(375px), tablet(768px), desktop(1440px).
+- Pixel restoration requirements are subject to the project agreement; if there is no agreement, the core structure, spacing, fonts, status and interaction will take precedence over mechanical pursuit of screenshot overlap.
+- Before implementing complex design tasks, a brief implementation plan is given, describing reused components, new components, possible changed files, responsive strategies and token mapping.
 
-## 设计 Token 与样式
+## Design Token and style
 
-- 优先使用已有 design token、CSS 变量或主题变量；不要硬编码颜色、圆角、间距、阴影和字体取值。
-- 缺少所需 token 时要明确指出，并集中补齐或记录，不在多个组件里散落字面量。
-- Tailwind 项目中，token 应通过语义化 `theme.extend`、CSS 变量或组件 variant 承接；不要把 `blue-600`、`rounded-xl` 等具体值复制成事实标准。
-- 组件 variant 应区分语义 tone、尺寸 size、密度 density 和状态 state；不要让一个字符串参数同时承载多种业务含义。
-- 动态 Tailwind class 必须可被构建扫描识别；复杂映射使用显式对象、variant 工具或 safelist。
-- 优先使用局部、受控的样式，不做大范围全局覆盖；与项目现有 CSS Modules、Tailwind、组件库或样式体系保持一致。
+- Prefer using existing design tokens, CSS variables, or theme variables; do not hard-code colors, rounded corners, spacing, shadows, and font values.
+- When required tokens are missing, clearly point them out and centrally complete or record them, rather than scattering literals in multiple components.
+- In the Tailwind project, tokens should be inherited through semantic `theme.extend`, CSS variables or component variants; do not copy specific values such as `blue-600` and `rounded-xl` into de facto standards.
+- Component variants should distinguish semantic tone, size, density and state; do not let a string parameter carry multiple business meanings at the same time.
+- Dynamic Tailwind classes must be recognized by build scans; use explicit objects, variant tools, or safelist for complex mappings.
+- Prioritize the use of local, controlled styles instead of large-scale global coverage; be consistent with the project's existing CSS Modules, Tailwind, component libraries or style systems.
 
-## 界面质感基线
+## Interface texture baseline
 
-- 嵌套圆角保持光学关系：外层圆角约等于内层圆角 + 间距。
-- 图标按钮、箭头、播放三角等非对称图形按视觉中心微调。
-- 小控件命中区域至少 40x40px，空间允许时优先 44x44px。
-- 标题和短文本可用 `text-wrap: balance`，短中正文可用 `text-wrap: pretty`。
-- 计数器、价格、时间、表格数字使用 `font-variant-numeric: tabular-nums`。
-- 动效只声明实际变化属性，禁止 `transition: all` 和 `will-change: all`，并尊重 `prefers-reduced-motion`。
+- Nested fillets maintain an optical relationship: the outer fillet is approximately equal to the inner fillet + spacing.
+- Asymmetric graphics such as icon buttons, arrows, and playback triangles are fine-tuned according to the visual center.
+- The hit area of the small control should be at least 40x40px, and 44x44px is preferred if space allows.
+- `text-wrap: balance` can be used for titles and short texts, and `text-wrap: pretty` can be used for short and medium text.
+- Use `font-variant-numeric: tabular-nums` for counters, prices, times, and tabular numbers.
+- Animation only declares actual change attributes, prohibits `transition: all` and `will-change: all`, and respects `prefers-reduced-motion`.
 
-## 暗色模式
+## Dark mode
 
-- 项目级暗色模式只选择一种主策略：CSS 变量、根节点 class、`data-theme` 或组件库主题。
-- 支持手动切换主题时，要在首屏绘制前初始化用户偏好，避免主题闪烁；实现细节交给 Tailwind / design-system skill reference。
-- 亮色与暗色都要复核 disabled、focus、selected、invalid、skeleton、chart、表单控件、第三方组件和阴影层级。
-- 不只靠降低透明度表达 disabled，不只补背景色而忽略文本、边框、图表和焦点状态。
+- Project-level dark mode only selects one main strategy: CSS variables, root node class, `data-theme` or component library theme.
+- When supporting manual theme switching, user preferences must be initialized before the first screen is drawn to avoid theme flickering; the implementation details are left to Tailwind / design-system skill reference.
+- Review disabled, focus, selected, invalid, skeleton, chart, form controls, third-party components and shadow levels for both light and dark colors.
+- Don't just reduce the transparency to express disabled, don't just fill in the background color and ignore text, borders, charts and focus states.
 
-## 可访问性基线
+## Accessibility Baseline
 
-- 优先使用语义化 HTML。
-- 表单控件具备标签，纯图标按钮具备可访问名称。
-- 菜单、标签页、对话框和自定义控件支持键盘操作。
-- 焦点样式可见，标题层级正确，真实表格数据使用表格语义。
-- 颜色对比度、触摸目标、reduced-motion 和错误提示不能被视觉 polish 破坏。
+- Prefer semantic HTML.
+- Form controls have labels and pure icon buttons have accessible names.
+- Menus, tabs, dialog boxes and custom controls support keyboard operation.
+- Focus styles are visible, title levels are correct, and real table data uses table semantics.
+- Color contrast, touch targets, reduced-motion and error prompts cannot be destroyed by visual polish.
 
-## UI 任务输出
+## UI task output
 
-实现完成后说明复用了什么、新建了什么、与设计稿或项目 token 的偏差、缺少哪些资源或交互细节。复杂 UI 还应说明状态覆盖、响应式验证和剩余设计风险。
+After the implementation is completed, explain what was reused, what was newly created, deviations from the design draft or project token, and what resources or interaction details are missing. Complex UIs should also account for state overrides, responsive validation, and remaining design risks.

package/templates/shared/rules/fec-error-handling.md

@@ -1,56 +1,56 @@
-# 错误处理规范
+# Error handling specifications
 
-本文件约定前端错误处理的常驻边界。React/Vue 组件边界细节交给对应框架 skill，API 错误映射和鉴权刷新交给 `fec-api-integration`，安全敏感错误交给 `fec-security-review`。
+This document agrees on the resident boundaries of front-end error handling. React/Vue component boundary details are handed over to the corresponding framework skill, API error mapping and authentication refresh are handed over to `fec-api-integration`, and security-sensitive errors are handed over to `fec-security-review`.
 
-## 错误分层
+## Error layering
 
-| 层级 | 错误类型 | 默认处理 |
+| Hierarchy | Error type | Default handling |
 | ---- | -------- | -------- |
-| 全局 | 未捕获异常、Promise rejection | 捕获、上报、全局降级 UI |
-| 路由 / 页面 | 页面级渲染异常 | Error Boundary / 框架错误边界 + 页面级降级 |
-| 模块 | 功能模块运行时异常 | 模块级边界 + 局部降级 |
-| 组件 / 请求 | 数据请求失败、操作失败 | 用户可理解提示 + 可恢复动作 |
-| 表单 | 校验失败 | 字段级错误提示和修正入口 |
+| Global | Uncaught exceptions, Promise rejection | Capture, reporting, global downgrade UI |
+| Routing / Page | Page-level rendering exception | Error Boundary / Frame error boundary + Page-level degradation |
+| Module | Function module runtime exception | Module-level boundary + local degradation |
+| Component/Request | Data request failure, operation failure | User-understandable prompts + recoverable actions |
+| Form | Validation failure | Field-level error prompts and correction entry |
 
-## 全局与模块边界
+## Global and module boundaries
 
-- 应在应用入口注册未捕获异常和 Promise rejection 监听，并接入项目错误上报平台。
-- React 使用项目统一的 Error Boundary 方案；业务组件保持函数式，不新增手写类组件边界。
-- Vue 使用项目统一的 `app.config.errorHandler`、`onErrorCaptured` 或框架级错误边界。
-- 独立功能模块应有局部降级能力，模块崩溃不应导致整个页面白屏。
-- Error Boundary 处理渲染异常；普通 API 失败应落到 loading/error/empty/data 状态和可恢复操作。
+- Uncaught exception and Promise rejection monitoring should be registered at the application entrance and connected to the project error reporting platform.
+- React uses the project's unified Error Boundary solution; business components remain functional and no new handwritten class component boundaries are added.
+- Vue uses project-unified `app.config.errorHandler`, `onErrorCaptured` or framework-level error boundaries.
+- Independent functional modules should have local downgrade capabilities, and module crashes should not cause the entire page to go blank.
+- Error Boundary handles rendering exceptions; normal API failures should fall into the loading/error/empty/data state and recoverable operations.
 
-## API 错误处理
+## API error handling
 
-- 请求层统一归一错误形状，组件不直接解析后端异常、token refresh 或重试策略。
-- 每类错误都应对应明确下一步：重试、重新登录、修改输入、返回上级、刷新冲突数据、联系支持或稍后再试。
-- `401`、`403`、`404`、`409`、`422`、`429`、`5xx` 和网络错误应有可区分的用户提示和日志语义。
-- UI 可显示 request id / trace id 方便支持排查，但不得暴露内部堆栈、SQL、服务名、密钥或敏感字段。
+- The request layer uniformly normalizes error shapes, and components do not directly parse backend exceptions, token refresh or retry strategies.
+- Each type of error should have a clear next step: retry, log in again, modify input, return to the previous level, refresh conflicting data, contact support, or try again later.
+- `401`, `403`, `404`, `409`, `422`, `429`, `5xx` and network errors should have distinguishable user prompts and log semantics.
+- The UI can display request id / trace id to facilitate support troubleshooting, but must not expose internal stacks, SQL, service names, keys or sensitive fields.
 
-## 用户体验
+## User experience
 
-- 每个数据展示区域处理 Loading、Error、Empty、Success 四种状态。
-- 全局级错误页提供返回首页、刷新或重试路径；模块级降级只影响该模块；操作级错误给出下一步。
-- 重试策略要克制：用户手动重试优先，自动重试需有上限、退避和停止条件。
-- 错误提示应保留用户已输入内容，避免因失败丢失表单或上下文。
+- Each data display area handles four states: Loading, Error, Empty, and Success.
+- Global-level error pages provide paths to return to the home page, refresh or retry; module-level downgrades only affect this module; operation-level errors provide the next step.
+- The retry strategy must be restrained: users’ manual retries are given priority, and automatic retries must have upper limits, backoff and stop conditions.
+- Error prompts should retain what the user has entered to avoid losing the form or context due to failure.
 
-## 错误上报
+## Error reporting
 
-上报内容应包含错误堆栈、页面 URL、浏览器/设备信息、用户或会话标识、操作上下文、请求标识和版本信息。上报前清理 token、密码、个人敏感字段和大体积 payload。
+The reported content should include the error stack, page URL, browser/device information, user or session ID, operation context, request ID, and version information. Clean tokens, passwords, personal sensitive fields and large payloads before reporting.
 
-## 反模式
+## Anti-pattern
 
-- 空 `catch` 块吞掉错误。
-- 所有错误统一用 `alert()` 或一个模糊 toast。
-- 接口失败时 UI 无反馈，或把后端原始异常直接展示给用户。
-- Error Boundary 没有重试或返回路径。
-- 在组件中到处写重复 `try/catch`，而不是统一封装请求边界。
-- 用 Error Boundary 承接普通 API 错误，导致用户无法理解或恢复。
+- Empty `catch` blocks swallow errors.
+- All errors are reported with `alert()` or a vague toast.
+- When the interface fails, there is no feedback from the UI, or the original exception from the backend is directly displayed to the user.
+- Error Boundary has no retry or return path.
+- Write repeated `try/catch` everywhere in the component instead of uniformly encapsulating request boundaries.
+- Use Error Boundary to handle common API errors, making it impossible for users to understand or recover.
 
-## 检查清单
+## Checklist
 
-- [ ] 全局未捕获异常和 Promise rejection 已监听。
-- [ ] 关键页面或模块有框架错误边界和局部降级 UI。
-- [ ] API 请求有统一错误归一、分级处理和可恢复动作。
-- [ ] 数据区域覆盖 Loading / Error / Empty / Success。
-- [ ] 错误上报包含足够定位信息且不泄露敏感数据。
+- [ ] Global uncaught exceptions and Promise rejections are listened to.
+- [ ] Critical pages or modules have frame error boundaries and partially degraded UI.
+- [ ] API requests have unified error normalization, hierarchical processing and recoverable actions.
+- [ ] Data area override Loading / Error / Empty / Success.
+- [ ] Error reports contain sufficient location information and do not leak sensitive data.

package/templates/shared/rules/fec-git-conventions.md

@@ -1,8 +1,8 @@
-# Git 提交规范
+# Git commit specifications
 
-凡是创建 commit、编写 commit message 或准备提交代码时，都应用本文件。
+This file should be used whenever creating a commit, writing a commit message, or preparing to submit code.
 
-## Conventional Commits 格式
+## Conventional Commits Format
 
 ```
 <type>(<scope>): <subject>
@@ -12,62 +12,62 @@
 [footer]
 ```
 
-### type 取值
+### type value
 
-| type | 用途 |
+| type | purpose |
 |------|------|
-| `feat` | 新功能 |
-| `fix` | 修复 bug |
-| `refactor` | 重构（不改变行为） |
-| `style` | 代码格式调整（不影响逻辑） |
-| `docs` | 文档变更 |
-| `test` | 测试相关 |
-| `chore` | 构建、工具、依赖等杂项 |
-| `perf` | 性能优化 |
-| `ci` | CI/CD 配置变更 |
+| `feat` | New features |
+| `fix` | Fix bug |
+| `refactor` | Refactor (does not change behavior) |
+| `style` | Code format adjustment (does not affect logic) |
+| `docs` | Documentation changes |
+| `test` | Test related |
+| `chore` | Build, tools, dependencies and other miscellaneous items |
+| `perf` | Performance optimization |
+| `ci` | CI/CD configuration changes |
 
 ### scope
 
-可选，标明影响范围，如模块名、组件名或功能域：
+Optional, indicate the scope of influence, such as module name, component name or functional domain:
 
-- `feat(auth): 新增手机号登录`
-- `fix(table): 修复排序列未高亮`
-- `refactor(api): 统一请求错误处理`
+- `feat(auth): add new mobile phone number to log in`
+- `fix(table): Fix sorting column not highlighted`
+- `refactor(api): unified request error handling`
 
-### subject 规范
+### subject specification
 
-- 使用祈使句（"增加 xxx" 而非 "增加了 xxx"）
-- 不超过 72 个字符
-- 不以句号结尾
-- 如果影响范围较大，在 body 中详细说明
+- Use imperative sentences ("increased xxx" instead of "increased xxx")
+- No more than 72 characters
+- does not end with a period
+- If the scope of impact is large, describe it in detail in the body
 
-## 分支命名
+## Branch naming
 
-- `feature/xxx` — 新功能
-- `fix/xxx` — 修复
-- `refactor/xxx` — 重构
-- `hotfix/xxx` — 紧急修复
+- `feature/xxx` — new features
+- `fix/xxx` — fix
+- `refactor/xxx` — Refactor
+- `hotfix/xxx` — emergency fix
 
-## 提交前检查
+## Check before submission
 
-提交前必须通过：
+Must pass before submission:
 
 1. lint
 2. type-check
-3. 与变更相关的测试
+3. Testing related to changes
 
-未经用户确认不要直接执行 `git commit`。
+Do not execute `git commit` directly without user confirmation.
 
-## 提交粒度
+## Submission granularity
 
-- 一个提交只包含一个清晰目的：功能、修复、测试、文档或清理。
-- 大型计划应拆成可验证的小批次，每批都有说明和命令结果。
-- 清理、格式化和行为变更不要混在同一提交中。
-- 推送或发 PR 前先复查 diff，确认没有本地配置、密钥、临时报告或调试输出。
+- A commit only has one clear purpose: feature, fix, test, documentation or cleanup.
+- Large programs should be broken into verifiable smaller batches, each with instructions and command results.
+- Don't mix cleanup, formatting, and behavior changes in the same commit.
+- Review the diff before pushing or sending a PR to make sure there are no local configurations, keys, temporary reports or debug output.
 
-## 反模式
+## Anti-pattern
 
-- 一个 commit 混合不相关的改动
-- commit message 过于笼统（如 "update"、"fix bug"、"wip"）
-- 在 commit 中包含调试代码、console.log 或临时 hack
-- 未说明验证命令或已知剩余风险就提交高风险改动
+- A commit that mixes unrelated changes
+- The commit message is too general (such as "update", "fix bug", "wip")
+- Include debug code, console.log, or temporary hacks in commits
+- Commit high-risk changes without specifying verification commands or knowing the remaining risk

package/templates/shared/rules/fec-i18n.md

@@ -1,64 +1,64 @@
-# 国际化 (i18n) 规则
+# Internationalization (i18n) rules
 
-凡是涉及用户可见文案、提示信息、表单标签、错误消息或 UI 文本时，都应用本文件。请根据项目实际 i18n 方案修改 locales 路径、库与 key 前缀。
+This document applies whenever it involves user-visible copy, tooltips, form labels, error messages, or UI text. Please modify the locales path, library and key prefix according to the actual i18n solution of the project.
 
-## 适用范围
+## Scope of application
 
-- **现代栈（React / Vue / Next / Nuxt 等）**：新增或修改的用户可见文案必须走项目 i18n 方案。
-- **遗留 HTML/JS、渐进迁移或新旧并存**：新代码路径仍须满足核心原则；遗留层遵守迁移约束，避免扩大硬编码和混乱 key。
+- **Modern stack (React/Vue/Next/Nuxt, etc.)**: New or modified user-visible copy must follow the project i18n solution.
+- **Legacy HTML/JS, progressive migration or coexistence of old and new**: The new code path must still meet the core principles; the legacy layer adheres to migration constraints to avoid expanding hard coding and confusing keys.
 
-下文用 `src/locales/` 指代项目实际文案资源目录，请按仓库约定替换。
+`src/locales/` is used below to refer to the actual copywriting resource directory of the project. Please replace it according to the warehouse convention.
 
-## 核心原则
+## Core Principles
 
-- 新应用代码中的用户可见文案须使用 i18n，禁止硬编码中文或英文字符串。
-- i18n key 按模块组织，使用点分命名，例如 `order.list.empty`。
-- 相同语义的文案复用同一个 key，避免重复定义。
-- 变量、复数、日期、数字和货币使用 i18n 能力格式化，不用字符串拼接。
-- 修改文案前先检索现有资源，优先复用准确 key。
+- User-visible copy in new application code must use i18n, and hardcoding Chinese or English strings is prohibited.
+- i18n keys are organized by modules and named with dots, such as `order.list.empty`.
+- Copies with the same semantics reuse the same key to avoid repeated definitions.
+- Variables, plurals, dates, numbers and currencies are formatted using i18n capabilities without string concatenation.
+- Search existing resources before modifying the copy, and give priority to reusing accurate keys.
 
-## 文案与资源规范
+## Copywriting and resource specifications
 
-- `common.*` 用于跨模块通用文案，例如确认、取消、提交、加载中。
-- `module.component.*` 用于模块级文案。
-- `validation.*` 用于表单校验提示。
-- `error.*` 用于错误信息。
-- 每种自然语言对应独立资源文件，禁止多种语言混写在同一文件或同一顶层多语言对象内。
-- 文案文件须以 UTF-8 保存；团队有约定时优先 UTF-8 无 BOM，避免中文、日文等非 ASCII 文案乱码。
-- 新增 key 时，同步更新当前功能应覆盖的主要语言文件；若某语言暂缺，必须显式记录缺口。
+- `common.*` is used for cross-module common copywriting, such as confirm, cancel, submit, and loading.
+- `module.component.*` is used for module-level copy.
+- `validation.*` is used for form validation prompts.
+- `error.*` for error messages.
+- Each natural language corresponds to an independent resource file, and multiple languages are prohibited from being mixed in the same file or the same top-level multi-language object.
+- Copywriting files must be saved in UTF-8; when the team has an agreement, priority will be given to UTF-8 without BOM to avoid garbled non-ASCII copywriting in Chinese, Japanese and other languages.
+- When adding a key, the main language files that should be covered by the current function are updated simultaneously; if a language is temporarily missing, the gap must be explicitly recorded.
 
-## 遗留代码与迁移场景
+## Legacy code and migration scenarios
 
-- 遗留 HTML 或 JS 中不新增用户可见硬编码，除非该段为纯静态展示且仓库尚无可接入 i18n 路径。
-- React / Vue 等新代码路径新增提示、错误、按钮、表单标签时，必须走 i18n。
-- 新增子应用或模块时，与现有语言文件结构、命名空间和懒加载策略一致。
-- key 按页面、模块和语义组织，避免继续沿用历史缩写或无意义分段。
-- 旧 key 若仅“能用但不准”，优先重命名 key 并重写译文，不长期保留并行兼容。
-- 仅当旧 key 已成为对外契约（后端、埋点、外部文档、第三方集成等固定引用）时，才引入映射层或别名过渡。
+- No new user-visible hardcoding is added in legacy HTML or JS, unless the segment is purely static and the repository does not yet have access to the i18n path.
+- When new code paths such as React/Vue add prompts, errors, buttons, and form labels, i18n must be used.
+- When adding new sub-applications or modules, they should be consistent with the existing language file structure, namespace and lazy loading strategy.
+- Keys are organized by page, module and semantics to avoid continuing to use historical abbreviations or meaningless segments.
+- If the old key is only "usable but inaccurate", priority will be given to renaming the key and rewriting the translation, and parallel compatibility will not be maintained for a long time.
+- Only introduce mapping layer or alias transition when the old key has become an external contract (fixed reference in backend, buried points, external documents, third-party integration, etc.).
 
-## 实现约束
+## Implement constraints
 
-- Vue、React、Next、Nuxt 的具体调用方式以项目现有 i18n 库为准，例如 `vue-i18n`、`react-intl`、`react-i18next` 或框架内置方案。
-- 组件中不要直接写用户可见硬编码；测试可通过 key 或最终文案断言，但应避免与翻译细节过度耦合。
-- 懒加载语言包时，loading、fallback 和缺失 key 行为要可预期。
-- 错误、表单和空状态文案要能表达用户下一步，不只翻译技术错误。
+- The specific calling methods of Vue, React, Next, and Nuxt are subject to the existing i18n library of the project, such as `vue-i18n`, `react-intl`, `react-i18next` or the framework's built-in solution.
+- Do not directly write user-visible hard coding in components; tests can assert through key or final copywriting, but should avoid over-coupling with translation details.
+- When lazily loading language packs, loading, fallback, and missing key behaviors must be predictable.
+- Error, form, and empty state copy should express the user’s next step, not just translate technical errors.
 
-## 检查清单
+## Checklist
 
-- [ ] 所有新增用户可见文案使用 i18n key。
-- [ ] 新增 key 已添加到所有应覆盖语言文件，且各语言分文件维护。
-- [ ] 语言资源文件为 UTF-8，打开无乱码。
-- [ ] key 命名符合模块、组件、用途约定，并复用已有语义。
-- [ ] 插值、复数、日期、数字、货币使用 i18n 格式化。
-- [ ] 迁移或混合栈中未扩大用户可见硬编码。
-- [ ] 新代码未破坏现有命名空间、加载方式和子应用边界。
+- [ ] All newly added user-visible copy uses i18n key.
+- [ ] The new key has been added to all language files that should be covered, and each language is maintained in separate files.
+- [ ] The language resource file is UTF-8, and there will be no garbled characters when opened.
+- [ ] key naming conforms to module, component, and usage conventions, and reuses existing semantics.
+- [ ] Interpolation, complex numbers, dates, numbers, currencies are formatted using i18n.
+- [ ] User-visible hardcoding not expanded in migration or hybrid stacks.
+- [ ] The new code does not break existing namespaces, loading methods, and sub-app boundaries.
 
-## 反模式
+## Anti-pattern
 
-- 在模板或 JSX 中直接写用户可见中文或英文字符串。
-- 使用字符串拼接代替 i18n 插值。
-- 在 JS/TS 逻辑中硬编码 toast、错误或确认文案。
-- 不同模块为相同含义创建不同 key。
-- 多语言混写导致 diff、评审和按需加载困难。
-- 用非 UTF-8 或错误编码保存文案文件。
-- 为迁就历史缩写或劣质命名长期保留多套并行 key。
+- Write user-visible Chinese or English strings directly in templates or JSX.
+- Use string concatenation instead of i18n interpolation.
+- Hardcode toast, error or confirmation text in JS/TS logic.
+- Different modules create different keys for the same meaning.
+- Mixing multiple languages makes diffing, reviewing and on-demand loading difficult.
+- Save copy files in non-UTF-8 or incorrect encoding.
+- Long-term retention of multiple sets of parallel keys to accommodate historical abbreviations or poor naming.