@qlover/create-app 0.7.14 → 0.8.0

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

@@ -0,0 +1,287 @@
+# 国际化 (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

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