@qlover/create-app 0.6.2 → 0.6.3

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

@@ -0,0 +1,268 @@
+# Internationalization System
+
+## Overview
+
+The internationalization system adopts an identifier-alias based approach, combining i18next and TypeScript comments to implement a type-safe, maintainable internationalization solution. Main features:
+
+- **Identifier Aliases**: Use constants instead of strings as translation keys
+- **TypeScript Comments**: Automatically generate translation resources through comments
+- **Type Safety**: Complete type checking and auto-completion
+- **Router Integration**: Support language parameters in URL paths
+- **Auto Generation**: Automatically generate translation files from source code
+- **Developer Friendly**: Complete development tool support
+
+## Core Concepts
+
+### 1. Identifier Aliases
+
+Use constants instead of string keys to provide better type safety and maintainability:
+
+```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. Auto Generation Configuration
+
+Configure auto generation in `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 Service Configuration
+
+```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;
+```
+
+## Usage
+
+### 1. Define Translation Keys
+
+```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. Using in Components
+
+```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. Translations with Parameters
+
+```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. Language Switching
+
+```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>
+  );
+}
+```
+
+## Best Practices
+
+### 1. Identifier Organization
+
+- **Naming Conventions**:
+
+  ```typescript
+  // Page related
+  PAGE_HOME_TITLE;
+  PAGE_ABOUT_DESCRIPTION;
+
+  // Feature module related
+  AUTH_LOGIN_BUTTON;
+  AUTH_LOGOUT_CONFIRM;
+
+  // Common component related
+  COMMON_SUBMIT_BUTTON;
+  COMMON_CANCEL_BUTTON;
+  ```
+
+- **File Organization**:
+  ```
+  config/
+  ├── Identifier/
+  │   ├── common.ts     // Common text
+  │   ├── page.ts       // Page text
+  │   ├── error.ts      // Error messages
+  │   └── auth.ts       // Authentication related
+  ```
+
+### 2. Comment Standards
+
+```typescript
+/**
+ * @description Brief description explaining text usage
+ * @localZh Chinese translation text
+ * @localEn English translation text
+ */
+```
+
+### 3. Type Safety
+
+```typescript
+// Use type imports to ensure key existence
+import * as i18nKeys from '@config/Identifier';
+
+// Type checking catches incorrect keys
+t(i18nKeys.NONEXISTENT_KEY); // TS error
+```
+
+### 4. Dynamic Content
+
+```typescript
+/**
+ * @description File upload progress
+ * @localZh 已上传 {{count}} 个文件，共 {{total}} 个
+ * @localEn Uploaded {{count}} files out of {{total}}
+ */
+export const UPLOAD_PROGRESS = 'upload.progress';
+
+// Usage
+t(i18nKeys.UPLOAD_PROGRESS, { count: 3, total: 10 });
+```
+
+## Workflow
+
+1. **Development Phase**:
+   - Define translation keys and comments in Identifier files
+   - Reference translations using identifier aliases in code
+   - Automatically generate translation files during development server runtime
+
+2. **Build Phase**:
+   - Automatically check translation completeness
+   - Generate production translation files
+   - Optimize translation resource loading
+
+3. **Runtime**:
+   - Detect language based on URL
+   - Load translation resources on demand
+   - Respond to language switch events
+
+## Common Issues
+
+### 1. Translations Not Working
+
+Check the following:
+
+- Ensure identifiers are correctly exported
+- Check if comment format is correct
+- Verify translation files are generated
+- Confirm language detection is working
+
+### 2. Type Errors
+
+Possible solutions:
+
+- Check identifier import paths
+- Ensure correct identifier usage
+- Update TypeScript type definitions
+
+### 3. Performance Optimization
+
+Development suggestions:
+
+- Reasonably split translation files
+- Use translation resource preloading
+- Avoid duplicate translation keys

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

@@ -0,0 +1,173 @@
+# React Application Development Documentation
+
+## Introduction
+
+This is a modern frontend application template based on React 18, integrating a complete development framework and toolchain. This template provides a comprehensive development solution, including state management, routing management, internationalization, theme system, and other core functionalities.
+
+### Key Features
+
+- 🚀 **Modern Technology Stack**: Based on React 18, TypeScript, Vite
+- 🎨 **Theme Customization**: Supports dynamic theme switching, dark mode
+- 🌍 **Internationalization**: Built-in multi-language support
+- 📦 **State Management**: Reactive state management based on publish-subscribe pattern
+- 🔑 **Authentication System**: Complete user authentication solution
+- 🛠️ **Development Tools**: ESLint, Prettier, TypeScript
+- 📱 **Responsive Design**: Supports multi-platform adaptation
+- 🧪 **Testing Support**: Integrated unit testing and component testing
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build production version
+npm run build
+```
+
+## Documentation Navigation
+
+### Architecture Guide
+
+- [Project Structure](./project-structure.md)
+- [Development Guidelines](./development-guide.md)
+- [Build and Deployment Guide](./deployment.md)
+
+### Core Features
+
+- [Router Development Guide](./router.md)
+- [State Management Guide](./store.md)
+- [Internationalization Guide](./i18n.md)
+- [Theme Development Guide](./theme.md)
+- [Request System Guide](./request.md)
+
+### Component Development
+
+- [Component Development Guide](./component-guide.md)
+- [TypeScript Development Standards](./typescript-guide.md)
+- [Styling Guide](./styling-guide.md)
+
+### Tools and Testing
+
+- [Testing Development Guide](./testing.md)
+- [Git Workflow Guide](./git-workflow.md)
+- [Performance Optimization Guide](./performance.md)
+
+### Security and Best Practices
+
+- [Security Development Guide](./security.md)
+- [Documentation Writing Guide](./documentation.md)
+
+## Directory Structure
+
+```
+docs/en/
+├── index.md                # This document
+├── project-structure.md    # Project structure explanation
+├── development-guide.md    # Development guidelines
+├── router.md              # Router development guide
+├── store.md               # State management guide
+├── i18n.md                # Internationalization guide
+├── theme.md               # Theme development guide
+└── ...
+```
+
+## Core Concepts
+
+### 1. Startup Process
+
+The application uses a plugin-based startup process:
+
+```
+Bootstrap Initialization → Load Plugins → Initialize Services → Render Application
+```
+
+### 2. State Management
+
+Reactive state management based on publish-subscribe pattern:
+
+```
+Action Trigger → Store Update → Component Re-render
+```
+
+### 3. Routing System
+
+Configuration-based route management:
+
+```
+Route Configuration → Auto-generate Routes → Code Splitting → Lazy Loading
+```
+
+### 4. Internationalization
+
+Automatic internationalization based on TypeScript comments:
+
+```
+Comment Definition → Auto-generate Resources → Dynamic Loading → Language Switching
+```
+
+## Development Process
+
+1. **Requirement Analysis**
+   - Understand business requirements
+   - Design technical solutions
+   - Evaluate development cycle
+
+2. **Development Phase**
+   - Follow development standards
+   - Write unit tests
+   - Conduct code reviews
+
+3. **Testing Phase**
+   - Unit testing
+   - Integration testing
+   - Performance testing
+
+4. **Deployment**
+   - Build optimization
+   - Deployment configuration
+   - Monitoring and alerts
+
+## Common Issues
+
+### 1. Development Environment Setup
+
+- Ensure Node.js version >= 16
+- Use recommended IDE configuration
+- Install necessary development tools
+
+### 2. Build Related
+
+- Common build error solutions
+- Performance optimization suggestions
+- Deployment considerations
+
+### 3. Development Related
+
+- Code standard issues
+- Type system usage
+- Component development standards
+
+## Contribution Guide
+
+1. Fork the project
+2. Create feature branch
+3. Submit changes
+4. Create Pull Request
+
+## Changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md) for detailed update history.
+
+## Support and Help
+
+- Submit Issues
+- Check Wiki
+- Participate in discussions
+
+## License
+
+This project is open-sourced under the [ISC License](../../LICENSE).