@robsun/create-keystone-app 0.2.7 → 0.2.9

package/package.json

@@ -1,6 +1,10 @@
-{
+{
   "name": "@robsun/create-keystone-app",
-  "version": "0.2.7",
+  "version": "0.2.9",
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepublishOnly": "node scripts/build.js && node scripts/prune-template-deps.js"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -15,8 +19,5 @@
   ],
   "engines": {
     "node": ">=18"
-  },
-  "scripts": {
-    "build": "node scripts/build.js"
   }
-}
+}

package/template/.claude/skills/keystone-dev/SKILL.md

@@ -10,11 +10,26 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 ## 工作流程
 
 1. **解析需求** → 识别所需能力
-2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
-3. **生成后端模块** → handler/, service/, repository/, migrations/
-4. **自动注册** → main.tsx + manifest.go + config.yaml
-5. **输出调整建议**
-6. **补测试并执行** → 见 references/testing.md
+2. **生成前端模块** → routes.tsx, pages/, services/, types.ts, locales/
+3. **生成后端模块** → handler/, service/, repository/, migrations/, i18n/
+4. **自动注册** → main.tsx + manifest.go + config.yaml
+5. **配置多语言** → 前端翻译文件 + 后端翻译键常量
+6. **输出调整建议**
+7. **补测试并执行** → 见 references/testing.md
+
+## 多语言最佳实践
+
+**前端**：
+- 所有用户可见文本必须使用 `t()` 翻译函数
+- 翻译键使用点记法：`{module}:{section}.{key}`
+- 避免硬编码文本，确保国际化覆盖率 100%
+
+**后端**：
+- 错误消息使用翻译键常量（keys.go）
+- API 响应消息根据请求语言返回
+- 使用 `i18n.T(c, key)` 获取翻译文本
+
+详见 [docs/I18N.md](../../docs/I18N.md)。
 
 ## 能力选择矩阵
 
@@ -27,13 +42,13 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 | 导入、批量 | DataImporter | ImportHandler + Job队列 |
 | 导出、下载 | DataExporter | ExportHandler + Job队列 |
 | 上传、附件 | FileUpload | UploadHandler + 存储服务 |
-| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
-| 权限 | PermissionGuard | 权限中间件 |
-
-审批流程与接入说明见 [references/approval.md](references/approval.md)。
-测试清单见 [references/testing.md](references/testing.md)。
-详细能力清单见 [references/CAPABILITIES.md](references/CAPABILITIES.md)。
-代码模板见 [references/TEMPLATES.md](references/TEMPLATES.md)。
+| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
+| 权限 | PermissionGuard | 权限中间件 |
+
+审批流程与接入说明见 [references/approval.md](references/approval.md)。
+测试清单见 [references/testing.md](references/testing.md)。
+详细能力清单见 [references/CAPABILITIES.md](references/CAPABILITIES.md)。
+代码模板见 [references/TEMPLATES.md](references/TEMPLATES.md)。
 
 ## 模块结构约定
 
@@ -48,7 +63,11 @@ apps/web/src/modules/{name}/
 │   └── Form.tsx          # ProForm
 ├── services/api.ts
 ├── types.ts
-└── help/index.md
+├── locales/              # 多语言翻译
+│   ├── zh-CN/{module}.json
+│   └── en-US/{module}.json
+└── help/
+    └── index.md
 ```
 
 ### 后端模块
@@ -59,6 +78,12 @@ apps/server/internal/modules/{name}/
 ├── domain/models/
 ├── domain/service/
 ├── infra/repository/
+├── i18n/                 # 多语言翻译
+│   ├── i18n.go
+│   ├── keys.go
+│   └── locales/
+│       ├── zh-CN.json
+│       └── en-US.json
 └── bootstrap/migrations/
 ```
 

package/template/.claude/skills/keystone-dev/references/CAPABILITIES.md

@@ -69,12 +69,46 @@ import { listNotifications, markNotificationRead, fetchUnreadCount } from '@robs
 import { getJob, listJobs } from '@robsun/keystone-web-core'
 ```
 
-### 8. Hooks
+### 8. 多语言 (i18n)
+```typescript
+// 翻译 Hook
+import { useTranslation } from 'react-i18next'
+
+// 使用示例
+const { t } = useTranslation()
+const title = t('module:key')  // 命名空间:键
+const description = t('common:actions.save')
+
+// 平台多语言配置
+import { getKeystoneConfig } from '@robsun/keystone-web-core'
+const locale = getKeystoneConfig().ui?.i18n?.defaultLocale // 'zh-CN' | 'en-US'
+
+// dayjs 本地化同步（自动完成）
+import dayjs from 'dayjs'
+dayjs.locale(getKeystoneConfig().ui?.locale?.dayjs ?? 'zh-cn')
+```
+
+**翻译文件组织**：
+```
+src/modules/{module}/locales/
+├── zh-CN/
+│   └── {namespace}.json
+└── en-US/
+    └── {namespace}.json
+```
+
+**命名空间约定**：
+- `common` - 通用文案（按钮、操作、状态等）
+- `auth` - 认证相关
+- `system` - 系统管理
+- `{module}` - 业务模块专属翻译
+
+### 9. Hooks
 ```typescript
 import { useListState } from '@robsun/keystone-web-core'
 ```
 
-### 9. 类型
+### 10. 类型
 ```typescript
 import type { ApiResponse, PaginatedData, PaginatedResponse } from '@robsun/keystone-web-core'
 import type { Permission, ModuleName, Action } from '@robsun/keystone-web-core'
@@ -126,3 +160,47 @@ storageService.Upload(...)
 storageService.Download(...)
 storageService.Delete(...)
 ```
+
+### 7. 多语言 (i18n)
+```go
+// 获取当前请求语言环境
+import "github.com/robsuncn/keystone/infra/i18n"
+
+locale := i18n.GetLocale(c)  // 从请求头或参数获取
+
+// 翻译函数
+i18n.T(c, "module.key")                    // 基础翻译
+i18n.T(c, "module.greeting", "name", "张三") // 带变量
+i18n.Tf(c, "module.count", count)          // 复数形式
+
+// 错误消息翻译
+return errors.New(i18n.T(c, "module.errors.notFound"))
+```
+
+**翻译文件组织**：
+```
+internal/modules/{module}/i18n/
+├── i18n.go                    # 初始化
+├── keys.go                    # 翻译键常量
+└── locales/
+    ├── zh-CN.json
+    └── en-US.json
+```
+
+**翻译键常量定义**：
+```go
+package i18n
+
+const (
+    KeyItemCreated    = "example.item.created"
+    KeyItemNotFound   = "example.item.notFound"
+    KeyItemInvalid    = "example.item.invalid"
+)
+```
+
+**模块初始化**：
+```go
+func init() {
+    i18n.MustLoadModuleTranslations("example", Translations)
+}
+```

package/template/.claude/skills/keystone-dev/references/TEMPLATES.md

@@ -157,6 +157,111 @@ export interface {Entity} {
 }
 ```
 
+### i18n 翻译文件
+
+**locales/zh-CN/{module}.json**
+```json
+{
+  "title": "{模块标题}",
+  "list": {
+    "title": "{实体}列表",
+    "empty": "暂无数据",
+    "columns": {
+      "name": "名称",
+      "status": "状态",
+      "createdAt": "创建时间"
+    }
+  },
+  "form": {
+    "create": "创建{实体}",
+    "edit": "编辑{实体}",
+    "fields": {
+      "name": "名称",
+      "description": "描述"
+    },
+    "placeholders": {
+      "name": "请输入名称"
+    }
+  },
+  "actions": {
+    "create": "新建",
+    "edit": "编辑",
+    "delete": "删除",
+    "save": "保存",
+    "cancel": "取消"
+  },
+  "messages": {
+    "createSuccess": "创建成功",
+    "updateSuccess": "更新成功",
+    "deleteSuccess": "删除成功",
+    "deleteConfirm": "确定要删除吗？"
+  }
+}
+```
+
+**locales/en-US/{module}.json**
+```json
+{
+  "title": "{Module Title}",
+  "list": {
+    "title": "{Entity} List",
+    "empty": "No data",
+    "columns": {
+      "name": "Name",
+      "status": "Status",
+      "createdAt": "Created At"
+    }
+  },
+  "form": {
+    "create": "Create {Entity}",
+    "edit": "Edit {Entity}",
+    "fields": {
+      "name": "Name",
+      "description": "Description"
+    },
+    "placeholders": {
+      "name": "Enter name"
+    }
+  },
+  "actions": {
+    "create": "Create",
+    "edit": "Edit",
+    "delete": "Delete",
+    "save": "Save",
+    "cancel": "Cancel"
+  },
+  "messages": {
+    "createSuccess": "Created successfully",
+    "updateSuccess": "Updated successfully",
+    "deleteSuccess": "Deleted successfully",
+    "deleteConfirm": "Are you sure to delete?"
+  }
+}
+```
+
+### 使用翻译的 List.tsx
+```tsx
+import { useTranslation } from 'react-i18next'
+import { ProTable } from '@robsun/keystone-web-core'
+
+export function Component() {
+  const { t } = useTranslation()  // 自动使用当前模块的命名空间
+
+  const columns = [
+    { title: t('{module}:list.columns.name'), dataIndex: 'name' },
+    { title: t('{module}:list.columns.status'), dataIndex: 'status' },
+    { title: t('{module}:list.columns.createdAt'), dataIndex: 'createdAt' },
+  ]
+
+  return (
+    <ProTable
+      columns={columns}
+      // ...
+    />
+  )
+}
+```
+
 ## 后端模板
 
 ### module.go
@@ -310,3 +415,118 @@ func (r *Repository) Delete(ctx context.Context, id string) error {
     return r.db.Delete(&models.{Entity}{}, "id = ?", id).Error
 }
 ```
+
+### i18n/i18n.go
+```go
+package i18n
+
+import (
+    "embed"
+    "github.com/robsuncn/keystone/infra/i18n"
+)
+
+//go:embed locales/*.json
+var Translations embed.FS
+
+func init() {
+    // 注册模块翻译文件
+    i18n.MustLoadModuleTranslations("{module}", Translations)
+}
+```
+
+### i18n/keys.go
+```go
+package i18n
+
+// 翻译键常量定义
+const (
+    // 成功消息
+    KeyItemCreated = "{module}.item.created"
+    KeyItemUpdated = "{module}.item.updated"
+    KeyItemDeleted = "{module}.item.deleted"
+
+    // 错误消息
+    KeyItemNotFound     = "{module}.item.notFound"
+    KeyItemInvalid      = "{module}.item.invalid"
+    KeyItemAlreadyExists = "{module}.item.alreadyExists"
+
+    // 验证消息
+    KeyNameRequired = "{module}.validation.nameRequired"
+    KeyNameTooLong  = "{module}.validation.nameTooLong"
+)
+```
+
+### i18n/locales/zh-CN.json
+```json
+{
+  "{module}": {
+    "item": {
+      "created": "{实体}创建成功",
+      "updated": "{实体}更新成功",
+      "deleted": "{实体}删除成功",
+      "notFound": "{实体}不存在",
+      "invalid": "{实体}数据无效",
+      "alreadyExists": "{实体}已存在"
+    },
+    "validation": {
+      "nameRequired": "名称不能为空",
+      "nameTooLong": "名称长度不能超过 {{max}} 个字符"
+    }
+  }
+}
+```
+
+### i18n/locales/en-US.json
+```json
+{
+  "{module}": {
+    "item": {
+      "created": "{Entity} created successfully",
+      "updated": "{Entity} updated successfully",
+      "deleted": "{Entity} deleted successfully",
+      "notFound": "{Entity} not found",
+      "invalid": "Invalid {entity} data",
+      "alreadyExists": "{Entity} already exists"
+    },
+    "validation": {
+      "nameRequired": "Name is required",
+      "nameTooLong": "Name cannot exceed {{max}} characters"
+    }
+  }
+}
+```
+
+### 使用翻译的 service.go
+```go
+package service
+
+import (
+    "errors"
+    "github.com/gin-gonic/gin"
+    "github.com/robsuncn/keystone/infra/i18n"
+    modulei18n "app/internal/modules/{module}/i18n"
+)
+
+func (s *Service) Get(c *gin.Context, id string) (*models.{Entity}, error) {
+    item, err := s.repo.Get(c, id)
+    if err != nil {
+        // 使用翻译键返回错误
+        return nil, errors.New(i18n.T(c, modulei18n.KeyItemNotFound))
+    }
+    return item, nil
+}
+
+func (s *Service) Create(c *gin.Context, entity *models.{Entity}) error {
+    if entity.Name == "" {
+        return errors.New(i18n.T(c, modulei18n.KeyNameRequired))
+    }
+
+    err := s.repo.Create(c, entity)
+    if err != nil {
+        return err
+    }
+
+    // 可以在日志或审计中使用翻译消息
+    return nil
+}
+```

package/template/.codex/skills/keystone-dev/SKILL.md

@@ -10,11 +10,26 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 ## 工作流程
 
 1. **解析需求** → 识别所需能力
-2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
-3. **生成后端模块** → handler/, service/, repository/, migrations/
-4. **自动注册** → main.tsx + manifest.go + config.yaml
-5. **输出调整建议**
-6. **补测试并执行** → 见 references/testing.md
+2. **生成前端模块** → routes.tsx, pages/, services/, types.ts, locales/
+3. **生成后端模块** → handler/, service/, repository/, migrations/, i18n/
+4. **自动注册** → main.tsx + manifest.go + config.yaml
+5. **配置多语言** → 前端翻译文件 + 后端翻译键常量
+6. **输出调整建议**
+7. **补测试并执行** → 见 references/testing.md
+
+## 多语言最佳实践
+
+**前端**：
+- 所有用户可见文本必须使用 `t()` 翻译函数
+- 翻译键使用点记法：`{module}:{section}.{key}`
+- 避免硬编码文本，确保国际化覆盖率 100%
+
+**后端**：
+- 错误消息使用翻译键常量（keys.go）
+- API 响应消息根据请求语言返回
+- 使用 `i18n.T(c, key)` 获取翻译文本
+
+详见 [docs/I18N.md](../../docs/I18N.md)。
 
 ## 能力选择矩阵
 
@@ -27,13 +42,13 @@ description: 基于 Keystone 平台开发业务模块。当用户需要创建新
 | 导入、批量 | DataImporter | ImportHandler + Job队列 |
 | 导出、下载 | DataExporter | ExportHandler + Job队列 |
 | 上传、附件 | FileUpload | UploadHandler + 存储服务 |
-| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
-| 权限 | PermissionGuard | 权限中间件 |
-
-审批流程与接入说明见 [references/approval.md](references/approval.md)。
-测试清单见 [references/testing.md](references/testing.md)。
-详细能力清单见 [references/CAPABILITIES.md](references/CAPABILITIES.md)。
-代码模板见 [references/TEMPLATES.md](references/TEMPLATES.md)。
+| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
+| 权限 | PermissionGuard | 权限中间件 |
+
+审批流程与接入说明见 [references/approval.md](references/approval.md)。
+测试清单见 [references/testing.md](references/testing.md)。
+详细能力清单见 [references/CAPABILITIES.md](references/CAPABILITIES.md)。
+代码模板见 [references/TEMPLATES.md](references/TEMPLATES.md)。
 
 ## 模块结构约定
 
@@ -48,7 +63,11 @@ apps/web/src/modules/{name}/
 │   └── Form.tsx          # ProForm
 ├── services/api.ts
 ├── types.ts
-└── help/index.md
+├── locales/              # 多语言翻译
+│   ├── zh-CN/{module}.json
+│   └── en-US/{module}.json
+└── help/
+    └── index.md
 ```
 
 ### 后端模块
@@ -59,6 +78,12 @@ apps/server/internal/modules/{name}/
 ├── domain/models/
 ├── domain/service/
 ├── infra/repository/
+├── i18n/                 # 多语言翻译
+│   ├── i18n.go
+│   ├── keys.go
+│   └── locales/
+│       ├── zh-CN.json
+│       └── en-US.json
 └── bootstrap/migrations/
 ```
 

package/template/.codex/skills/keystone-dev/references/CAPABILITIES.md

@@ -69,12 +69,46 @@ import { listNotifications, markNotificationRead, fetchUnreadCount } from '@robs
 import { getJob, listJobs } from '@robsun/keystone-web-core'
 ```
 
-### 8. Hooks
+### 8. 多语言 (i18n)
+```typescript
+// 翻译 Hook
+import { useTranslation } from 'react-i18next'
+
+// 使用示例
+const { t } = useTranslation()
+const title = t('module:key')  // 命名空间:键
+const description = t('common:actions.save')
+
+// 平台多语言配置
+import { getKeystoneConfig } from '@robsun/keystone-web-core'
+const locale = getKeystoneConfig().ui?.i18n?.defaultLocale // 'zh-CN' | 'en-US'
+
+// dayjs 本地化同步（自动完成）
+import dayjs from 'dayjs'
+dayjs.locale(getKeystoneConfig().ui?.locale?.dayjs ?? 'zh-cn')
+```
+
+**翻译文件组织**：
+```
+src/modules/{module}/locales/
+├── zh-CN/
+│   └── {namespace}.json
+└── en-US/
+    └── {namespace}.json
+```
+
+**命名空间约定**：
+- `common` - 通用文案（按钮、操作、状态等）
+- `auth` - 认证相关
+- `system` - 系统管理
+- `{module}` - 业务模块专属翻译
+
+### 9. Hooks
 ```typescript
 import { useListState } from '@robsun/keystone-web-core'
 ```
 
-### 9. 类型
+### 10. 类型
 ```typescript
 import type { ApiResponse, PaginatedData, PaginatedResponse } from '@robsun/keystone-web-core'
 import type { Permission, ModuleName, Action } from '@robsun/keystone-web-core'
@@ -126,3 +160,47 @@ storageService.Upload(...)
 storageService.Download(...)
 storageService.Delete(...)
 ```
+
+### 7. 多语言 (i18n)
+```go
+// 获取当前请求语言环境
+import "github.com/robsuncn/keystone/infra/i18n"
+
+locale := i18n.GetLocale(c)  // 从请求头或参数获取
+
+// 翻译函数
+i18n.T(c, "module.key")                    // 基础翻译
+i18n.T(c, "module.greeting", "name", "张三") // 带变量
+i18n.Tf(c, "module.count", count)          // 复数形式
+
+// 错误消息翻译
+return errors.New(i18n.T(c, "module.errors.notFound"))
+```
+
+**翻译文件组织**：
+```
+internal/modules/{module}/i18n/
+├── i18n.go                    # 初始化
+├── keys.go                    # 翻译键常量
+└── locales/
+    ├── zh-CN.json
+    └── en-US.json
+```
+
+**翻译键常量定义**：
+```go
+package i18n
+
+const (
+    KeyItemCreated    = "example.item.created"
+    KeyItemNotFound   = "example.item.notFound"
+    KeyItemInvalid    = "example.item.invalid"
+)
+```
+
+**模块初始化**：
+```go
+func init() {
+    i18n.MustLoadModuleTranslations("example", Translations)
+}
+```