@robsun/create-keystone-app 0.2.6 → 0.2.8

package/template/apps/server/internal/modules/example/module.go

@@ -12,6 +12,7 @@ import (
 	exampleseeds "__APP_NAME__/apps/server/internal/modules/example/bootstrap/seeds"
 	examplemodels "__APP_NAME__/apps/server/internal/modules/example/domain/models"
 	exampleservice "__APP_NAME__/apps/server/internal/modules/example/domain/service"
+	examplei18n "__APP_NAME__/apps/server/internal/modules/example/i18n"
 	examplerepository "__APP_NAME__/apps/server/internal/modules/example/infra/repository"
 )
 
@@ -50,18 +51,23 @@ func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
 	if reg == nil {
 		return nil
 	}
-	if err := reg.CreateMenu("example:item", "Example Items", "example", 10); err != nil {
+	// Use NameKey for i18n support
+	if err := reg.CreateMenuI18n("example:item", "Example Items", "permission.example.item", "example", 10); err != nil {
 		return err
 	}
-	if err := reg.CreateAction("example:item:view", "View Items", "example", "example:item"); err != nil {
+	if err := reg.CreateActionI18n("example:item:view", "View Items", "permission.example.item.view", "example", "example:item"); err != nil {
 		return err
 	}
-	if err := reg.CreateAction("example:item:manage", "Manage Items", "example", "example:item"); err != nil {
+	if err := reg.CreateActionI18n("example:item:manage", "Manage Items", "permission.example.item.manage", "example", "example:item"); err != nil {
 		return err
 	}
 	return nil
 }
 
+func (m *Module) RegisterI18n() error {
+	return examplei18n.RegisterLocales()
+}
+
 func (m *Module) RegisterJobs(_ *jobs.Registry) error {
 	return nil
 }

package/template/apps/web/package.json

@@ -17,11 +17,13 @@
   },
   "dependencies": {
     "@ant-design/icons": "^6.1.0",
-    "@robsun/keystone-web-core": "0.1.9",
+    "@robsun/keystone-web-core": "^0.2.0",
     "antd": "^6.0.1",
     "dayjs": "^1.11.19",
+    "i18next": "^24.2.3",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "react-i18next": "^15.5.1",
     "react-router-dom": "^7.10.1"
   },
   "devDependencies": {

package/template/apps/web/src/app.config.ts

@@ -13,5 +13,12 @@ export const appConfig: Partial<KeystoneWebConfig> = {
   approval: {
     businessTypes: [{ value: 'general', label: 'General Flow' }],
   },
+  ui: {
+    i18n: {
+      enabled: true,
+      defaultLocale: 'zh-CN',
+      supportedLocales: ['zh-CN', 'en-US'],
+    },
+  },
 }
-
+

package/template/apps/web/src/modules/example/index.ts

@@ -1,4 +1,10 @@
-import { registerModule } from '@robsun/keystone-web-core'
+import { registerModule, loadModuleLocales } from '@robsun/keystone-web-core'
 import { exampleRoutes } from './routes'
 
+// Load module i18n translations
+loadModuleLocales('example', {
+  'zh-CN': () => import('./locales/zh-CN/example.json'),
+  'en-US': () => import('./locales/en-US/example.json'),
+})
+
 registerModule({ name: 'example', routes: exampleRoutes })

package/template/apps/web/src/modules/example/locales/en-US/example.json

@@ -0,0 +1,32 @@
+{
+  "menu": {
+    "items": "Example Items"
+  },
+  "page": {
+    "title": "Example Items",
+    "createButton": "Create Item"
+  },
+  "table": {
+    "name": "Name",
+    "description": "Description",
+    "status": "Status",
+    "createdAt": "Created At",
+    "actions": "Actions"
+  },
+  "form": {
+    "nameLabel": "Name",
+    "namePlaceholder": "Enter name",
+    "descriptionLabel": "Description",
+    "descriptionPlaceholder": "Enter description"
+  },
+  "messages": {
+    "createSuccess": "Created successfully",
+    "updateSuccess": "Updated successfully",
+    "deleteSuccess": "Deleted successfully",
+    "loadFailed": "Failed to load"
+  },
+  "status": {
+    "active": "Active",
+    "inactive": "Inactive"
+  }
+}

package/template/apps/web/src/modules/example/locales/zh-CN/example.json

@@ -0,0 +1,32 @@
+{
+  "menu": {
+    "items": "示例列表"
+  },
+  "page": {
+    "title": "示例项目",
+    "createButton": "新建项目"
+  },
+  "table": {
+    "name": "名称",
+    "description": "描述",
+    "status": "状态",
+    "createdAt": "创建时间",
+    "actions": "操作"
+  },
+  "form": {
+    "nameLabel": "名称",
+    "namePlaceholder": "请输入名称",
+    "descriptionLabel": "描述",
+    "descriptionPlaceholder": "请输入描述"
+  },
+  "messages": {
+    "createSuccess": "创建成功",
+    "updateSuccess": "更新成功",
+    "deleteSuccess": "删除成功",
+    "loadFailed": "加载失败"
+  },
+  "status": {
+    "active": "启用",
+    "inactive": "停用"
+  }
+}

package/template/apps/web/src/modules/example/pages/ExampleItemsPage.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { App, Button, Card, Form, Input, Modal, Popconfirm, Select, Space, Table, Tag, Typography } from 'antd'
 import type { ColumnsType } from 'antd/es/table'
+import { useTranslation } from 'react-i18next'
 import dayjs from 'dayjs'
 import {
   createExampleItem,
@@ -16,17 +17,14 @@ type ExampleItemFormValues = {
   status: ExampleItemStatus
 }
 
-const statusMeta: Record<ExampleItemStatus, { label: string; color: string }> = {
-  active: { label: 'Active', color: 'success' },
-  inactive: { label: 'Inactive', color: 'default' },
+const statusColors: Record<ExampleItemStatus, string> = {
+  active: 'success',
+  inactive: 'default',
 }
 
-const statusOptions = [
-  { value: 'active', label: 'Active' },
-  { value: 'inactive', label: 'Inactive' },
-]
-
 export function ExampleItemsPage() {
+  const { t } = useTranslation('example')
+  const { t: tc } = useTranslation('common')
   const { message } = App.useApp()
   const [items, setItems] = useState<ExampleItem[]>([])
   const [loading, setLoading] = useState(false)
@@ -35,18 +33,26 @@ export function ExampleItemsPage() {
   const [editingItem, setEditingItem] = useState<ExampleItem | null>(null)
   const [form] = Form.useForm<ExampleItemFormValues>()
 
+  const statusOptions = useMemo(
+    () => [
+      { value: 'active', label: t('status.active') },
+      { value: 'inactive', label: t('status.inactive') },
+    ],
+    [t]
+  )
+
   const fetchItems = useCallback(async () => {
     setLoading(true)
     try {
       const data = await listExampleItems()
       setItems(data)
     } catch (err) {
-      const detail = err instanceof Error ? err.message : 'Failed to load items'
+      const detail = err instanceof Error ? err.message : t('messages.loadFailed')
       message.error(detail)
     } finally {
       setLoading(false)
     }
-  }, [message])
+  }, [message, t])
 
   useEffect(() => {
     void fetchItems()
@@ -104,98 +110,94 @@ export function ExampleItemsPage() {
     try {
       if (editingItem) {
         await updateExampleItem(editingItem.id, payload)
-        message.success('Item updated')
+        message.success(t('messages.updateSuccess'))
       } else {
         await createExampleItem(payload)
-        message.success('Item created')
+        message.success(t('messages.createSuccess'))
       }
       closeModal()
       await fetchItems()
     } catch (err) {
-      const detail = err instanceof Error ? err.message : 'Failed to save item'
+      const detail = err instanceof Error ? err.message : tc('messages.operationFailed')
       message.error(detail)
     } finally {
       setSaving(false)
     }
-  }, [closeModal, editingItem, fetchItems, form, message])
+  }, [closeModal, editingItem, fetchItems, form, message, t, tc])
 
   const handleDelete = useCallback(
     async (id: number) => {
       try {
         await deleteExampleItem(id)
         await fetchItems()
-        message.success('Item deleted')
+        message.success(t('messages.deleteSuccess'))
       } catch (err) {
-        const detail = err instanceof Error ? err.message : 'Failed to delete item'
+        const detail = err instanceof Error ? err.message : tc('messages.operationFailed')
         message.error(detail)
       }
     },
-    [fetchItems, message]
+    [fetchItems, message, t, tc]
   )
 
   const columns: ColumnsType<ExampleItem> = useMemo(
     () => [
-      { title: 'Title', dataIndex: 'title', key: 'title' },
+      { title: t('table.name'), dataIndex: 'title', key: 'title' },
       {
-        title: 'Description',
+        title: t('table.description'),
         dataIndex: 'description',
         key: 'description',
         render: (value: string) =>
           value ? <Typography.Text type="secondary">{value}</Typography.Text> : '-',
       },
       {
-        title: 'Status',
+        title: t('table.status'),
         dataIndex: 'status',
         key: 'status',
-        render: (value: ExampleItemStatus) => {
-          const meta = statusMeta[value]
-          return <Tag color={meta.color}>{meta.label}</Tag>
-        },
+        render: (value: ExampleItemStatus) => (
+          <Tag color={statusColors[value]}>{t(`status.${value}`)}</Tag>
+        ),
       },
       {
-        title: 'Updated',
+        title: tc('table.updatedAt'),
         dataIndex: 'updated_at',
         key: 'updated_at',
         render: (value: string) => (value ? dayjs(value).format('YYYY-MM-DD HH:mm') : '-'),
       },
       {
-        title: 'Actions',
+        title: tc('table.actions'),
         key: 'actions',
         render: (_, record) => (
           <Space>
             <Button type="link" onClick={() => openEdit(record)}>
-              Edit
+              {tc('actions.edit')}
             </Button>
-            <Popconfirm title="Delete this item?" onConfirm={() => handleDelete(record.id)}>
+            <Popconfirm title={tc('confirm.deleteContent')} onConfirm={() => handleDelete(record.id)}>
               <Button type="link" danger>
-                Delete
+                {tc('actions.delete')}
               </Button>
             </Popconfirm>
           </Space>
         ),
       },
     ],
-    [handleDelete, openEdit]
+    [handleDelete, openEdit, t, tc]
   )
 
   return (
     <Card
-      title="Example Items"
+      title={t('page.title')}
       extra={
         <Space>
           <Button onClick={fetchItems} loading={loading}>
-            Refresh
+            {tc('actions.refresh')}
           </Button>
           <Button type="primary" onClick={openCreate}>
-            New Item
+            {t('page.createButton')}
           </Button>
         </Space>
       }
     >
-      <Space orientation="vertical" size="middle" style={{ width: '100%' }}>
-        <Typography.Text type="secondary">
-          This page demonstrates a full CRUD workflow wired to the Example module API.
-        </Typography.Text>
+      <Space direction="vertical" size="middle" style={{ width: '100%' }}>
         <Table<ExampleItem>
           rowKey="id"
           loading={loading}
@@ -206,26 +208,26 @@ export function ExampleItemsPage() {
       </Space>
 
       <Modal
-        title={editingItem ? 'Edit Item' : 'New Item'}
+        title={editingItem ? tc('actions.edit') : tc('actions.create')}
         open={modalOpen}
         onCancel={closeModal}
         onOk={handleSubmit}
         confirmLoading={saving}
-        okText={editingItem ? 'Save' : 'Create'}
+        okText={editingItem ? tc('actions.save') : tc('actions.create')}
         destroyOnHidden
       >
         <Form form={form} layout="vertical" initialValues={{ status: 'active' }}>
           <Form.Item
-            label="Title"
+            label={t('form.nameLabel')}
             name="title"
-            rules={[{ required: true, whitespace: true, message: 'Title is required' }]}
+            rules={[{ required: true, whitespace: true, message: tc('form.required') }]}
           >
-            <Input placeholder="Item title" allowClear />
+            <Input placeholder={t('form.namePlaceholder')} allowClear />
           </Form.Item>
-          <Form.Item label="Description" name="description">
-            <Input.TextArea rows={3} placeholder="Short description" />
+          <Form.Item label={t('form.descriptionLabel')} name="description">
+            <Input.TextArea rows={3} placeholder={t('form.descriptionPlaceholder')} />
           </Form.Item>
-          <Form.Item label="Status" name="status" rules={[{ required: true, message: 'Select status' }]}>
+          <Form.Item label={t('table.status')} name="status" rules={[{ required: true, message: tc('form.required') }]}>
             <Select options={statusOptions} />
           </Form.Item>
         </Form>

package/template/apps/web/src/modules/example/routes.tsx

@@ -31,8 +31,12 @@ export const exampleRoutes: RouteObject[] = [
     path: 'example',
     element: <ExampleItemsPage />,
     handle: {
-      menu: { label: 'Example Items', icon: <AppstoreOutlined />, permission: 'example:item:view' },
-      breadcrumb: 'Example Items',
+      menu: {
+        labelKey: 'example:menu.items',
+        icon: <AppstoreOutlined />,
+        permission: 'example:item:view',
+      },
+      breadcrumbKey: 'example:menu.items',
       permission: 'example:item:view',
       helpKey: 'example/items',
     },

package/template/docs/CONVENTIONS.md

@@ -146,7 +146,79 @@ RegisterPermissions 负责定义权限种子与后台管理项
 - Go 通过 `//go:embed` 嵌入前端产物。
 - 保留 `apps/server/internal/frontend/dist/.gitkeep`，避免 embed 找不到目录。
 
+## 多语言支持 (i18n)
+
+> 详细指南请参考 [I18N.md](./I18N.md)
+
+### 启用多语言
+在 `apps/web/src/app.config.ts` 中配置：
+```ts
+export const appConfig: Partial<KeystoneWebConfig> = {
+  // ...
+  ui: {
+    i18n: {
+      enabled: true,
+      defaultLocale: 'zh-CN',
+      supportedLocales: ['zh-CN', 'en-US'],
+    },
+  },
+}
+```
+
+### 前端模块 i18n
+1. 创建语言包目录 `modules/<module>/locales/zh-CN/*.json` 和 `en-US/*.json`
+2. 在 `modules/<module>/index.ts` 注册：
+```ts
+import { registerModule, loadModuleLocales } from '@robsun/keystone-web-core'
+
+loadModuleLocales('myModule', {
+  'zh-CN': () => import('./locales/zh-CN/myModule.json'),
+  'en-US': () => import('./locales/en-US/myModule.json'),
+})
+
+registerModule({ name: 'myModule', routes: myRoutes })
+```
+
+3. 路由配置使用 `labelKey` 和 `breadcrumbKey`：
+```tsx
+{
+  path: 'items',
+  handle: {
+    menu: {
+      label: '项目列表',          // 回退文案
+      labelKey: 'myModule:menu.items',  // i18n 键（优先）
+      icon: <AppstoreOutlined />,
+    },
+    breadcrumb: '项目列表',
+    breadcrumbKey: 'myModule:menu.items',
+  },
+}
+```
+
+4. 在组件中使用翻译：
+```tsx
+import { useTranslation } from 'react-i18next'
+
+function MyComponent() {
+  const { t } = useTranslation('myModule')
+  return <Button>{t('actions.save')}</Button>
+}
+```
+
+### 后端 i18n
+后端已内置 i18n 支持，使用 `Accept-Language` 请求头自动选择语言：
+```go
+import "your-project/infra/i18n"
+
+// 响应
+response.SuccessI18n(c, i18n.MsgCreated, data)
+response.BadRequestI18n(c, i18n.MsgInvalidRequest)
+
+// 自定义错误
+return &i18n.I18nError{Key: "order.notFound"}
+```
+
 ## Testing
 - Web：`pnpm -C apps/web test`（Vitest）。
 - Server：`go -C apps/server test ./...`。
-- 全量：`pnpm test`。
+- 全量：`pnpm test`。