@qlover/create-app 0.7.14 → 0.8.0

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

@@ -0,0 +1,287 @@
+# 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

@@ -0,0 +1,165 @@
+# 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).