@qlover/create-app 0.6.1 → 0.6.3

package/dist/templates/react-app/docs/zh/i18n.md

@@ -0,0 +1,268 @@
+# 国际化系统
+
+## 概述
+
+国际化系统采用基于标识符别名的方案，结合 i18next 和 TypeScript 注释，实现了一个类型安全、易维护的国际化解决方案。主要特点：
+
+- **标识符别名**：使用常量而非字符串作为翻译键
+- **TypeScript 注释**：通过注释自动生成翻译资源
+- **类型安全**：完整的类型检查和自动补全
+- **路由集成**：支持 URL 路径中的语言参数
+- **自动生成**：自动从源码生成翻译文件
+- **开发友好**：完整的开发工具支持
+
+## 核心概念
+
+### 1. 标识符别名
+
+使用常量替代字符串键值，提供更好的类型安全和维护性：
+
+```typescript
+// config/Identifier/common.ts
+
+/**
+ * @description Theme switcher default theme label
+ * @localZh 默认主题
+ * @localEn Default Theme
+ */
+export const HEADER_THEME_DEFAULT = 'header.theme.default';
+
+/**
+ * @description Theme switcher dark theme label
+ * @localZh 暗色主题
+ * @localEn Dark Theme
+ */
+export const HEADER_THEME_DARK = 'header.theme.dark';
+```
+
+### 2. 自动生成配置
+
+在 `vite.config.ts` 中配置自动生成：
+
+```typescript
+import ts2Locales from '@brain-toolkit/ts2locales/vite';
+
+export default defineConfig({
+  plugins: [
+    ts2Locales({
+      locales: ['en', 'zh'],
+      options: [
+        {
+          source: './config/Identifier/common.ts',
+          target: './public/locales/{{lng}}/common.json'
+        },
+        {
+          source: './config/Identifier/error.ts',
+          target: './public/locales/{{lng}}/common.json'
+        }
+      ]
+    })
+  ]
+});
+```
+
+### 3. i18n 服务配置
+
+```typescript
+// config/i18n.ts
+export default {
+  fallbackLng: 'en',
+  debug: false,
+  interpolation: {
+    escapeValue: false
+  },
+  ns: ['common'],
+  defaultNS: 'common',
+  backend: {
+    loadPath: '/locales/{{lng}}/{{ns}}.json'
+  },
+  supportedLngs: ['en', 'zh']
+} as const;
+```
+
+## 使用方式
+
+### 1. 定义翻译键
+
+```typescript
+// config/Identifier/page.ts
+
+/**
+ * @description Home page title
+ * @localZh 首页
+ * @localEn Home
+ */
+export const PAGE_HOME_TITLE = 'page.home.title';
+
+/**
+ * @description Home page welcome message
+ * @localZh 欢迎来到我们的应用
+ * @localEn Welcome to our application
+ */
+export const PAGE_HOME_WELCOME = 'page.home.welcome';
+```
+
+### 2. 在组件中使用
+
+```tsx
+import { useTranslation } from 'react-i18next';
+import * as i18nKeys from '@config/Identifier/page';
+
+function HomePage() {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t(i18nKeys.PAGE_HOME_TITLE)}</h1>
+      <p>{t(i18nKeys.PAGE_HOME_WELCOME)}</p>
+    </div>
+  );
+}
+```
+
+### 3. 带参数的翻译
+
+```typescript
+/**
+ * @description Welcome user message
+ * @localZh 欢迎，{{name}}！
+ * @localEn Welcome, {{name}}!
+ */
+export const USER_WELCOME = 'user.welcome';
+
+function Welcome({ username }: { username: string }) {
+  const { t } = useTranslation();
+  return <h1>{t(i18nKeys.USER_WELCOME, { name: username })}</h1>;
+}
+```
+
+### 4. 语言切换
+
+```tsx
+import { IOC } from '@/core/IOC';
+import { I18nService } from '@/base/services/I18nService';
+
+function LanguageSwitcher() {
+  const i18nService = IOC(I18nService);
+  const currentLang = i18nService.getCurrentLanguage();
+
+  const handleChange = (lang: string) => {
+    i18nService.changeLanguage(lang);
+  };
+
+  return (
+    <select value={currentLang} onChange={(e) => handleChange(e.target.value)}>
+      <option value="zh">中文</option>
+      <option value="en">English</option>
+    </select>
+  );
+}
+```
+
+## 最佳实践
+
+### 1. 标识符组织
+
+- **命名规范**：
+
+  ```typescript
+  // 页面相关
+  PAGE_HOME_TITLE;
+  PAGE_ABOUT_DESCRIPTION;
+
+  // 功能模块相关
+  AUTH_LOGIN_BUTTON;
+  AUTH_LOGOUT_CONFIRM;
+
+  // 公共组件相关
+  COMMON_SUBMIT_BUTTON;
+  COMMON_CANCEL_BUTTON;
+  ```
+
+- **文件组织**：
+  ```
+  config/
+  ├── Identifier/
+  │   ├── common.ts     // 公共文本
+  │   ├── page.ts       // 页面文本
+  │   ├── error.ts      // 错误信息
+  │   └── auth.ts       // 认证相关
+  ```
+
+### 2. 注释规范
+
+```typescript
+/**
+ * @description 简短的描述，说明文本用途
+ * @localZh 中文翻译文本
+ * @localEn 英文翻译文本
+ */
+```
+
+### 3. 类型安全
+
+```typescript
+// 使用类型导入确保键值存在
+import * as i18nKeys from '@config/Identifier';
+
+// 类型检查会捕获错误的键值
+t(i18nKeys.NONEXISTENT_KEY); // TS 错误
+```
+
+### 4. 动态内容
+
+```typescript
+/**
+ * @description File upload progress
+ * @localZh 已上传 {{count}} 个文件，共 {{total}} 个
+ * @localEn Uploaded {{count}} files out of {{total}}
+ */
+export const UPLOAD_PROGRESS = 'upload.progress';
+
+// 使用
+t(i18nKeys.UPLOAD_PROGRESS, { count: 3, total: 10 });
+```
+
+## 工作流程
+
+1. **开发阶段**：
+   - 在 Identifier 文件中定义翻译键和注释
+   - 使用标识符别名在代码中引用翻译
+   - 运行开发服务器时自动生成翻译文件
+
+2. **构建阶段**：
+   - 自动检查翻译完整性
+   - 生成生产环境翻译文件
+   - 优化翻译资源加载
+
+3. **运行时**：
+   - 根据 URL 检测语言
+   - 按需加载翻译资源
+   - 响应语言切换事件
+
+## 常见问题
+
+### 1. 翻译未生效
+
+检查以下几点：
+
+- 确保标识符正确导出
+- 检查注释格式是否规范
+- 验证翻译文件是否生成
+- 确认语言检测正确
+
+### 2. 类型错误
+
+可能的解决方案：
+
+- 检查标识符导入路径
+- 确保使用正确的标识符
+- 更新 TypeScript 类型定义
+
+### 3. 性能优化
+
+开发建议：
+
+- 合理拆分翻译文件
+- 使用翻译资源预加载
+- 避免重复翻译键

package/dist/templates/react-app/docs/zh/index.md

@@ -0,0 +1,173 @@
+# React 应用开发文档
+
+## 简介
+
+这是一个基于 React 18 的现代化前端应用模板，集成了完整的开发框架和工具链。本模板提供了一套完整的开发解决方案，包括状态管理、路由管理、国际化、主题系统等核心功能。
+
+### 主要特性
+
+- 🚀 **现代化技术栈**：基于 React 18、TypeScript、Vite
+- 🎨 **主题定制**：支持动态主题切换，深色模式
+- 🌍 **国际化**：内置多语言支持
+- 📦 **状态管理**：基于发布订阅的响应式状态管理
+- 🔑 **认证系统**：完整的用户认证解决方案
+- 🛠️ **开发工具**：ESLint、Prettier、TypeScript
+- 📱 **响应式设计**：支持多端适配
+- 🧪 **测试支持**：集成单元测试和组件测试
+
+## 快速开始
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建生产版本
+npm run build
+```
+
+## 文档导航
+
+### 架构指南
+
+- [项目结构说明](./project-structure.md)
+- [开发规范指南](./development-guide.md)
+- [构建部署指南](./deployment.md)
+
+### 核心功能
+
+- [路由开发指南](./router.md)
+- [状态管理指南](./store.md)
+- [国际化开发指南](./i18n.md)
+- [主题开发指南](./theme.md)
+- [请求系统指南](./request.md)
+
+### 组件开发
+
+- [组件开发指南](./component-guide.md)
+- [TypeScript 开发规范](./typescript-guide.md)
+- [样式开发指南](./styling-guide.md)
+
+### 工具和测试
+
+- [测试开发指南](./testing.md)
+- [Git 工作流指南](./git-workflow.md)
+- [性能优化指南](./performance.md)
+
+### 安全和最佳实践
+
+- [安全开发指南](./security.md)
+- [文档编写指南](./documentation.md)
+
+## 目录结构
+
+```
+docs/zh/
+├── index.md                # 本文档
+├── project-structure.md    # 项目结构说明
+├── development-guide.md    # 开发规范指南
+├── router.md              # 路由开发指南
+├── store.md               # 状态管理指南
+├── i18n.md                # 国际化开发指南
+├── theme.md               # 主题开发指南
+└── ...
+```
+
+## 核心概念
+
+### 1. 启动流程
+
+应用采用插件化的启动流程：
+
+```
+Bootstrap 初始化 → 加载插件 → 初始化服务 → 渲染应用
+```
+
+### 2. 状态管理
+
+基于发布订阅模式的响应式状态管理：
+
+```
+Action 触发 → Store 更新 → 组件重渲染
+```
+
+### 3. 路由系统
+
+配置式路由管理：
+
+```
+路由配置 → 自动生成路由 → 代码分割 → 按需加载
+```
+
+### 4. 国际化
+
+基于 TypeScript 注释的自动国际化：
+
+```
+注释定义 → 自动生成资源 → 动态加载 → 语言切换
+```
+
+## 开发流程
+
+1. **需求分析**
+   - 理解业务需求
+   - 设计技术方案
+   - 评估开发周期
+
+2. **开发阶段**
+   - 遵循开发规范
+   - 编写单元测试
+   - 进行代码审查
+
+3. **测试阶段**
+   - 单元测试
+   - 集成测试
+   - 性能测试
+
+4. **部署上线**
+   - 构建优化
+   - 部署配置
+   - 监控告警
+
+## 常见问题
+
+### 1. 开发环境配置
+
+- 确保 Node.js 版本 >= 16
+- 使用推荐的 IDE 配置
+- 安装必要的开发工具
+
+### 2. 构建相关
+
+- 常见构建错误解决
+- 性能优化建议
+- 部署注意事项
+
+### 3. 开发相关
+
+- 代码规范问题
+- 类型系统使用
+- 组件开发规范
+
+## 贡献指南
+
+1. Fork 项目
+2. 创建特性分支
+3. 提交变更
+4. 发起 Pull Request
+
+## 更新日志
+
+查看 [CHANGELOG.md](../../CHANGELOG.md) 了解详细的更新历史。
+
+## 支持和帮助
+
+- 提交 Issue
+- 查看 Wiki
+- 参与讨论
+
+## 许可证
+
+本项目基于 [ISC 许可证](../../LICENSE) 开源。