@qlover/create-app 1.1.0 → 2.0.0

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

@@ -1,287 +0,0 @@
-# 国际化 (i18n) 指南
-
-本文档将详细介绍项目中的国际化实现，包括 API 错误信息、页面内容以及所有需要多语言支持的文本内容。
-
-## 目录
-
-- [基础配置](#基础配置)
-- [API 错误信息处理](#api-错误信息处理)
-- [页面内容国际化](#页面内容国际化)
-- [使用规范](#使用规范)
-
-## 基础配置
-
-项目使用 next-intl 进行国际化管理，配置文件位于 `config/i18n/i18nConfig.ts`：
-
-```typescript
-export const i18nConfig = {
-  localeNames: {
-    en: 'English',
-    zh: '中文'
-  },
-  fallbackLng: 'en',
-  supportedLngs: ['en', 'zh'],
-  localeDetection: true
-};
-```
-
-所有支持的语言都在 `supportedLngs` 中定义，默认语言为 `fallbackLng` 指定的语言。
-
-## API 错误信息处理
-
-API 错误信息的国际化处理流程如下：
-
-1. API 响应格式：
-
-```typescript
-interface AppApiErrorInterface {
-  success: false;
-  id: string; // i18n key
-  message?: string; // 可选的直接显示消息
-}
-```
-
-2. 错误处理流程：
-   - API 请求通过 `AppApiPlugin` 处理响应
-   - 如果响应表示错误，错误信息会被转换为 `ExecutorError`
-   - `DialogErrorPlugin` 负责显示错误消息
-   - 如果错误消息是 i18n key 格式（如 "namespace_key"），则会通过 i18n 服务翻译后显示
-   - 如果不是 i18n key 格式，则直接显示原始消息
-
-示例：
-
-```typescript
-// API 返回错误
-{
-  success: false,
-  id: "error_invalid_password"
-}
-
-// DialogErrorPlugin 会自动翻译并显示对应语言的错误信息
-```
-
-## 页面内容国际化
-
-### PageI18nInterface
-
-`PageI18nInterface` 是一个核心接口，用于定义页面的国际化内容和 SEO 元数据。这个接口提供了完整的页面元数据结构，包括基本 SEO 信息、Open Graph、Twitter Card 等。
-
-```typescript
-interface PageI18nInterface {
-  // 基本元数据属性
-  title: string; // 页面标题
-  description: string; // 页面描述
-  content: string; // 页面内容
-  keywords: string; // 页面关键词
-
-  // 规范链接
-  canonical?: string; // 可选的规范链接
-
-  // 爬虫控制
-  robots?: {
-    index?: boolean; // 是否允许索引
-    follow?: boolean; // 是否跟随链接
-    noarchive?: boolean; // 是否允许存档
-  };
-
-  // Open Graph 元数据
-  og?: {
-    title?: string; // OG 标题
-    description?: string; // OG 描述
-    type?: string; // 内容类型
-    image?: string; // 图片 URL
-    url?: string; // 页面 URL
-    siteName?: string; // 站点名称
-    locale?: string; // 语言地区
-  };
-
-  // Twitter Card 元数据
-  twitter?: {
-    card?: 'summary' | 'summary_large_image' | 'app' | 'player'; // 卡片类型
-    site?: string; // Twitter 站点
-    creator?: string; // 创建者
-    title?: string; // Twitter 标题
-    description?: string; // Twitter 描述
-    image?: string; // Twitter 图片
-  };
-
-  // 附加元数据
-  author?: string; // 作者
-  publishedTime?: string; // 发布时间
-  modifiedTime?: string; // 修改时间
-}
-```
-
-使用说明：
-
-1. 所有字符串类型的值都可以是：
-   - i18n key：将会被翻译成当前语言
-   - 直接字符串：将直接使用，不进行翻译
-2. 可选字段（带 `?` 的字段）表示该页面可以不包含这些元数据
-3. 这个接口通常用于：
-   - 定义页面的 SEO 信息
-   - 生成 meta 标签
-   - 提供社交媒体分享信息
-   - 控制搜索引擎爬虫行为
-
-### 在页面中使用 PageI18nInterface
-
-以下是一个完整的页面示例，展示如何使用 PageI18nInterface：
-
-```typescript
-// 1. 首先定义页面的 i18n 接口
-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. 在页面中使用
-export async function generateMetadata({ params }: { params: PageParamsType }): Promise<Metadata> {
-  const pageParams = new PageParams(await params);
-  // 获取页面 SEO 元数据
-  return await pageParams.getI18nInterface(homeI18n);
-}
-
-export default async function HomePage({ params }: PageParamsProps) {
-  const pageParams = new PageParams(await params!);
-  // 获取页面翻译内容
-  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>
-  );
-}
-```
-
-这个示例展示了：
-
-1. 如何定义页面特定的 i18n 接口
-2. 如何使用 `getI18nInterface` 获取翻译后的内容
-3. 如何在页面元数据中使用 i18n
-4. 如何在页面组件中使用翻译的内容
-
-### 实现页面国际化
-
-页面内容的国际化主要通过以下方式实现：
-
-1. 页面 i18n 接口定义：
-
-```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. 获取翻译内容：
-
-```typescript
-// 在页面组件中
-const messages = await getMessages({ locale });
-// 或者使用 PageParams
-const i18nContent = await pageParams.getI18nInterface(homeI18n);
-```
-
-3. 动态路由中的语言处理：
-
-```typescript
-// src/app/[locale]/layout.tsx
-export default async function RootLayout({ children, params }) {
-  const pageParams = new PageParams(params);
-  const locale = pageParams.getI18nWithNotFound();
-  // ...
-}
-```
-
-## 使用规范
-
-1. **所有文本内容必须使用 i18n key**：
-   - 不要直接在代码中写入固定文本
-   - 所有文本都应该定义在 i18n 配置文件中
-   - 使用有意义的 key 名称，如：`PAGE_HOME_TITLE`、`ERROR_INVALID_INPUT`
-
-2. **i18n key 命名规范**：
-   - 使用大写字母和下划线
-   - 使用有意义的前缀表示分类，如：
-     - `PAGE_` 前缀表示页面相关
-     - `ERROR_` 前缀表示错误信息
-     - `COMMON_` 前缀表示通用文本
-
-3. **翻译文件组织**：
-   - 翻译文件位于 `public/locales/` 目录
-   - 按语言代码分类：`en.json`、`zh.json`
-   - 保持所有语言文件的 key 一致
-
-4. **类型安全**：
-   - 使用 TypeScript 接口定义 i18n 内容
-   - 所有 i18n key 都应该在 `config/Identifier/` 目录下定义
-   - 使用 `Object.freeze` 确保 i18n 对象不被修改
-
-5. **最佳实践**：
-   - 使用 `PageParams` 类处理页面的语言相关逻辑
-   - 在组件中使用 `useTranslations` hook 获取翻译
-   - API 错误信息优先使用 i18n key，而不是硬编码的消息
-   - 确保所有用户可见的文本都支持多语言
-
-## 示例
-
-1. 页面组件中使用 i18n：
-
-```typescript
-export function LoginForm(props: { tt: LoginI18nInterface }) {
-  const { tt } = props;
-
-  return (
-    <form>
-      <h1>{tt.title}</h1>
-      <p>{tt.description}</p>
-      {/* ... */}
-    </form>
-  );
-}
-```
-
-2. API 错误处理：
-
-```typescript
-// 后端返回错误
-throw new AppErrorApi({
-  id: 'ERROR_INVALID_CREDENTIALS',
-  success: false
-});
-
-// 前端自动处理并显示翻译后的错误消息
-```
-
-3. 动态内容：
-
-```typescript
-const t = await getTranslations({
-  locale: pageParams.getLocale(),
-  namespace: 'common'
-});
-
-const message = t('welcome', {
-  name: userName
-});
-```

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

@@ -1,165 +0,0 @@
-# Next.js 全栈应用开发文档
-
-## 简介
-
-这是一个基于 Next.js 的全栈应用模板，采用面向接口的设计模式，实现了清晰的分层架构。本模板提供了完整的全栈开发解决方案，包括服务端API、客户端状态管理、认证授权、国际化等核心功能。
-
-### 主要特性
-
-- 🏗️ **全栈架构**：基于 Next.js 的应用路由和API路由
-- 🔌 **接口驱动**：完整的面向接口编程实践
-- 🎨 **主题定制**：基于 Tailwind CSS 的主题系统
-- 🌍 **国际化**：基于 next-intl 的多语言支持
-- 🔄 **依赖注入**：基于 TypeScript 的 IOC 容器
-- 🛡️ **身份认证**：完整的认证和授权方案
-- 📡 **分层设计**：清晰的前后端分层架构
-- 🎮 **状态管理**：基于控制器模式的状态管理
-- 🔗 **数据访问**：灵活的数据库访问层
-
-## 快速开始
-
-```bash
-# 安装依赖
-pnpm install
-
-# 开发环境启动
-pnpm dev
-# cross-env APP_ENV=localhost next dev --turbopack --port 3100
-# 自动加载 .env.localhost -> .env
-
-# 预发环境启动
-pnpm dev:staging
-# cross-env APP_ENV=staging next dev --turbopack --port 3100
-# 自动加载 .env.staging -> .env
-
-# 构建生产版本
-pnpm build
-```
-
-## 架构概览
-
-### 1. 客户端架构
-
-#### 接口定义 (src/base/port)
-
-- AppUserApiInterface: 用户API接口
-- AsyncStateInterface: 异步状态接口
-- RouterInterface: 路由管理接口
-
-#### 核心实现
-
-- 控制器层：状态和业务逻辑管理
-- 服务层：API调用和数据处理
-- UI组件：可复用的展示组件
-
-### 2. 服务端架构
-
-#### 接口定义 (src/server/port)
-
-- ServerAuthInterface: 认证接口
-- DBBridgeInterface: 数据库操作接口
-- UserRepositoryInterface: 用户仓库接口
-- ValidatorInterface: 数据验证接口
-
-#### 核心实现
-
-- API路由层：请求处理和响应
-- 服务层：业务逻辑实现
-- 数据访问层：仓库和数据库交互
-
-## 开发指南
-
-### 1. API 开发流程
-
-1. 定义接口 (src/server/port)
-2. 实现验证器 (src/server/validators)
-3. 实现服务层 (src/server/services)
-4. 实现数据访问 (src/server/repositorys)
-5. 创建API路由 (src/app/api)
-
-### 2. 页面开发流程
-
-1. 创建页面组件 (src/app/[locale])
-2. 实现页面控制器
-3. 添加API服务
-4. 注册IOC容器
-
-### 3. 最佳实践
-
-#### 接口优先开发
-
-- 先定义接口，再实现具体类
-- 保持接口的单一职责
-- 使用依赖注入管理依赖
-
-#### 分层原则
-
-- 保持层级间的清晰边界
-- 通过接口进行层级间通信
-- 避免跨层级直接调用
-
-#### 状态管理
-
-- 使用控制器管理复杂状态
-- 保持状态的不可变性
-- 统一的状态更新流程
-
-## 核心功能文档
-
-### 基础架构
-
-- [项目结构说明](./project-structure.md)
-- [开发规范指南](./development-guide.md)
-- [环境配置指南](./env.md)
-
-### 服务端开发
-
-- [API开发指南](./api.md)
-- [认证授权](./auth.md)
-- [数据访问层](./database.md)
-- [验证器开发](./validator.md)
-
-### 客户端开发
-
-- [页面开发指南](./page.md)
-- [组件开发](./component.md)
-
-### 功能模块
-
-- [国际化开发](./i18n.md)
-- [主题系统](./theme.md)
-- [路由管理](./router.md)
-
-## 常见问题
-
-### 1. 开发环境配置
-
-- Node.js >= 16
-- pnpm >= 8.0
-- 推荐使用 VSCode + 推荐插件
-
-### 2. 开发相关
-
-- 接口设计规范
-- 依赖注入使用
-- 控制器开发规范
-
-### 3. 部署相关
-
-- 环境变量配置
-- 构建优化
-- 部署流程
-
-## 更新日志
-
-查看 [CHANGELOG.md](../../CHANGELOG.md) 了解详细的更新历史。
-
-## 支持和帮助
-
-- 提交 Issue
-- 查看 Wiki
-- 参与讨论
-
-## 许可证
-
-本项目基于 [ISC 许可证](../../LICENSE) 开源。