@qlover/create-app 1.1.0 → 2.0.0

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

@@ -1,287 +0,0 @@
-# Internationalization (i18n) Guide
-
-This document details the implementation of internationalization in the project, including API error messages, page content, and all text content requiring multi-language support.
-
-## Table of Contents
-
-- [Basic Configuration](#basic-configuration)
-- [API Error Message Handling](#api-error-message-handling)
-- [Page Content Internationalization](#page-content-internationalization)
-- [Usage Guidelines](#usage-guidelines)
-
-## Basic Configuration
-
-The project uses next-intl for internationalization management, with configuration located in `config/i18n/i18nConfig.ts`:
-
-```typescript
-export const i18nConfig = {
-  localeNames: {
-    en: 'English',
-    zh: '中文'
-  },
-  fallbackLng: 'en',
-  supportedLngs: ['en', 'zh'],
-  localeDetection: true
-};
-```
-
-All supported languages are defined in `supportedLngs`, with the default language specified by `fallbackLng`.
-
-## API Error Message Handling
-
-The internationalization process for API error messages is as follows:
-
-1. API Response Format:
-
-```typescript
-interface AppApiErrorInterface {
-  success: false;
-  id: string; // i18n key
-  message?: string; // Optional direct display message
-}
-```
-
-2. Error Handling Process:
-   - API requests are processed through `AppApiPlugin`
-   - If the response indicates an error, it's converted to `ExecutorError`
-   - `DialogErrorPlugin` handles displaying error messages
-   - If the error message is in i18n key format (e.g., "namespace_key"), it's translated through the i18n service before display
-   - If not in i18n key format, the original message is displayed directly
-
-Example:
-
-```typescript
-// API returns error
-{
-  success: false,
-  id: "error_invalid_password"
-}
-
-// DialogErrorPlugin will automatically translate and display the error message in the appropriate language
-```
-
-## Page Content Internationalization
-
-### PageI18nInterface
-
-`PageI18nInterface` is a core interface defining internationalization content and SEO metadata for pages. This interface provides a complete page metadata structure, including basic SEO information, Open Graph, Twitter Card, etc.
-
-```typescript
-interface PageI18nInterface {
-  // Basic metadata properties
-  title: string; // Page title
-  description: string; // Page description
-  content: string; // Page content
-  keywords: string; // Page keywords
-
-  // Canonical link
-  canonical?: string; // Optional canonical link
-
-  // Crawler control
-  robots?: {
-    index?: boolean; // Allow indexing
-    follow?: boolean; // Follow links
-    noarchive?: boolean; // Allow archiving
-  };
-
-  // Open Graph metadata
-  og?: {
-    title?: string; // OG title
-    description?: string; // OG description
-    type?: string; // Content type
-    image?: string; // Image URL
-    url?: string; // Page URL
-    siteName?: string; // Site name
-    locale?: string; // Language locale
-  };
-
-  // Twitter Card metadata
-  twitter?: {
-    card?: 'summary' | 'summary_large_image' | 'app' | 'player'; // Card type
-    site?: string; // Twitter site
-    creator?: string; // Creator
-    title?: string; // Twitter title
-    description?: string; // Twitter description
-    image?: string; // Twitter image
-  };
-
-  // Additional metadata
-  author?: string; // Author
-  publishedTime?: string; // Publication time
-  modifiedTime?: string; // Modification time
-}
-```
-
-Usage Notes:
-
-1. All string type values can be:
-   - i18n key: Will be translated to the current language
-   - Direct string: Will be used directly, without translation
-2. Optional fields (with `?`) indicate metadata that pages may not include
-3. This interface is typically used for:
-   - Defining page SEO information
-   - Generating meta tags
-   - Providing social media sharing information
-   - Controlling search engine crawler behavior
-
-### Using PageI18nInterface in Pages
-
-Here's a complete page example showing how to use PageI18nInterface:
-
-```typescript
-// 1. First define the page's i18n interface
-export const homeI18n = Object.freeze({
-  title: i18nKeys.PAGE_HOME_TITLE,
-  description: i18nKeys.PAGE_HOME_DESCRIPTION,
-  content: i18nKeys.PAGE_HOME_DESCRIPTION,
-  keywords: i18nKeys.PAGE_HOME_KEYWORDS,
-
-  welcome: i18nKeys.HOME_WELCOME,
-  getStartedTitle: i18nKeys.HOME_GET_STARTED_TITLE,
-  getStartedDescription: i18nKeys.HOME_GET_STARTED_DESCRIPTION,
-  getStartedButton: i18nKeys.HOME_GET_STARTED_BUTTON
-});
-
-// 2. Use in page
-export async function generateMetadata({ params }: { params: PageParamsType }): Promise<Metadata> {
-  const pageParams = new PageParams(await params);
-  // Get page SEO metadata
-  return await pageParams.getI18nInterface(homeI18n);
-}
-
-export default async function HomePage({ params }: PageParamsProps) {
-  const pageParams = new PageParams(await params!);
-  // Get page translation content
-  const tt = await pageParams.getI18nInterface(homeI18n);
-
-  return (
-    <BaseLayout>
-      <section>
-        <h1>{tt.welcome}</h1>
-        <p>{tt.description}</p>
-        <div>
-          <h2>{tt.getStartedTitle}</h2>
-          <p>{tt.getStartedDescription}</p>
-          <Button>{tt.getStartedButton}</Button>
-        </div>
-      </section>
-    </BaseLayout>
-  );
-}
-```
-
-This example demonstrates:
-
-1. How to define page-specific i18n interfaces
-2. How to use `getI18nInterface` to get translated content
-3. How to use i18n in page metadata
-4. How to use translated content in page components
-
-### Implementing Page Internationalization
-
-Page content internationalization is primarily implemented through:
-
-1. Page i18n Interface Definition:
-
-```typescript
-// config/i18n/HomeI18n.ts
-export const homeI18n = Object.freeze({
-  title: i18nKeys.PAGE_HOME_TITLE,
-  description: i18nKeys.PAGE_HOME_DESCRIPTION,
-  welcome: i18nKeys.HOME_WELCOME
-  // ...
-});
-```
-
-2. Getting Translated Content:
-
-```typescript
-// In page component
-const messages = await getMessages({ locale });
-// Or using PageParams
-const i18nContent = await pageParams.getI18nInterface(homeI18n);
-```
-
-3. Language Handling in Dynamic Routes:
-
-```typescript
-// src/app/[locale]/layout.tsx
-export default async function RootLayout({ children, params }) {
-  const pageParams = new PageParams(params);
-  const locale = pageParams.getI18nWithNotFound();
-  // ...
-}
-```
-
-## Usage Guidelines
-
-1. **All Text Content Must Use i18n Keys**:
-   - Don't write fixed text directly in code
-   - All text should be defined in i18n configuration files
-   - Use meaningful key names, e.g., `PAGE_HOME_TITLE`, `ERROR_INVALID_INPUT`
-
-2. **i18n Key Naming Conventions**:
-   - Use uppercase letters and underscores
-   - Use meaningful prefixes to indicate categories, such as:
-     - `PAGE_` prefix for page-related content
-     - `ERROR_` prefix for error messages
-     - `COMMON_` prefix for common text
-
-3. **Translation File Organization**:
-   - Translation files located in `public/locales/` directory
-   - Categorized by language code: `en.json`, `zh.json`
-   - Maintain consistent keys across all language files
-
-4. **Type Safety**:
-   - Use TypeScript interfaces to define i18n content
-   - All i18n keys should be defined in the `config/Identifier/` directory
-   - Use `Object.freeze` to ensure i18n objects aren't modified
-
-5. **Best Practices**:
-   - Use `PageParams` class for page language-related logic
-   - Use `useTranslations` hook in components to get translations
-   - Prioritize i18n keys for API error messages over hardcoded messages
-   - Ensure all user-visible text supports multiple languages
-
-## Examples
-
-1. Using i18n in Page Components:
-
-```typescript
-export function LoginForm(props: { tt: LoginI18nInterface }) {
-  const { tt } = props;
-
-  return (
-    <form>
-      <h1>{tt.title}</h1>
-      <p>{tt.description}</p>
-      {/* ... */}
-    </form>
-  );
-}
-```
-
-2. API Error Handling:
-
-```typescript
-// Backend returns error
-throw new AppErrorApi({
-  id: 'ERROR_INVALID_CREDENTIALS',
-  success: false
-});
-
-// Frontend automatically handles and displays translated error message
-```
-
-3. Dynamic Content:
-
-```typescript
-const t = await getTranslations({
-  locale: pageParams.getLocale(),
-  namespace: 'common'
-});
-
-const message = t('welcome', {
-  name: userName
-});
-```

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

@@ -1,165 +0,0 @@
-# Next.js Full-Stack Application Documentation
-
-## Introduction
-
-This is a full-stack application template based on Next.js, implementing a clear layered architecture using an interface-driven design pattern. This template provides a complete full-stack development solution, including server-side API, client-side state management, authentication and authorization, internationalization, and other core features.
-
-### Key Features
-
-- 🏗️ **Full-Stack Architecture**: Based on Next.js app router and API routes
-- 🔌 **Interface-Driven**: Complete interface-oriented programming practice
-- 🎨 **Theme Customization**: Theme system based on Tailwind CSS
-- 🌍 **Internationalization**: Multi-language support based on next-intl
-- 🔄 **Dependency Injection**: TypeScript-based IOC container
-- 🛡️ **Authentication**: Complete authentication and authorization solution
-- 📡 **Layered Design**: Clear front-end and back-end layered architecture
-- 🎮 **State Management**: Controller pattern-based state management
-- 🔗 **Data Access**: Flexible database access layer
-
-## Quick Start
-
-```bash
-# Install dependencies
-pnpm install
-
-# Development environment startup
-pnpm dev
-# cross-env APP_ENV=localhost next dev --turbopack --port 3100
-# Automatically loads .env.localhost -> .env
-
-# Staging environment startup
-pnpm dev:staging
-# cross-env APP_ENV=staging next dev --turbopack --port 3100
-# Automatically loads .env.staging -> .env
-
-# Build production version
-pnpm build
-```
-
-## Architecture Overview
-
-### 1. Client-Side Architecture
-
-#### Interface Definitions (src/base/port)
-
-- AppUserApiInterface: User API interface
-- AsyncStateInterface: Asynchronous state interface
-- RouterInterface: Router management interface
-
-#### Core Implementation
-
-- Controller Layer: State and business logic management
-- Service Layer: API calls and data processing
-- UI Components: Reusable presentation components
-
-### 2. Server-Side Architecture
-
-#### Interface Definitions (src/server/port)
-
-- ServerAuthInterface: Authentication interface
-- DBBridgeInterface: Database operation interface
-- UserRepositoryInterface: User repository interface
-- ValidatorInterface: Data validation interface
-
-#### Core Implementation
-
-- API Route Layer: Request handling and response
-- Service Layer: Business logic implementation
-- Data Access Layer: Repository and database interaction
-
-## Development Guide
-
-### 1. API Development Process
-
-1. Define interface (src/server/port)
-2. Implement validator (src/server/validators)
-3. Implement service layer (src/server/services)
-4. Implement data access (src/server/repositorys)
-5. Create API route (src/app/api)
-
-### 2. Page Development Process
-
-1. Create page component (src/app/[locale])
-2. Implement page controller
-3. Add API service
-4. Register IOC container
-
-### 3. Best Practices
-
-#### Interface-First Development
-
-- Define interfaces before implementing concrete classes
-- Maintain single responsibility for interfaces
-- Use dependency injection to manage dependencies
-
-#### Layering Principles
-
-- Maintain clear boundaries between layers
-- Communicate between layers through interfaces
-- Avoid direct cross-layer calls
-
-#### State Management
-
-- Use controllers to manage complex state
-- Maintain state immutability
-- Unified state update process
-
-## Core Feature Documentation
-
-### Basic Architecture
-
-- [Project Structure](./project-structure.md)
-- [Development Guidelines](./development-guide.md)
-- [Environment Configuration](./env.md)
-
-### Server-Side Development
-
-- [API Development Guide](./api.md)
-- [Authentication & Authorization](./auth.md)
-- [Data Access Layer](./database.md)
-- [Validator Development](./validator.md)
-
-### Client-Side Development
-
-- [Page Development Guide](./page.md)
-- [Component Development](./component.md)
-
-### Feature Modules
-
-- [Internationalization Development](./i18n.md)
-- [Theme System](./theme.md)
-- [Router Management](./router.md)
-
-## FAQ
-
-### 1. Development Environment Setup
-
-- Node.js >= 16
-- pnpm >= 8.0
-- VSCode + recommended extensions recommended
-
-### 2. Development Related
-
-- Interface design specifications
-- Dependency injection usage
-- Controller development guidelines
-
-### 3. Deployment Related
-
-- Environment variable configuration
-- Build optimization
-- Deployment process
-
-## Changelog
-
-View [CHANGELOG.md](../../CHANGELOG.md) for detailed update history.
-
-## Support and Help
-
-- Submit Issues
-- View Wiki
-- Join Discussions
-
-## License
-
-This project is open-sourced under the [ISC License](../../LICENSE).