@robsun/create-keystone-app 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,10 @@
-{
+{
   "name": "@robsun/create-keystone-app",
-  "version": "0.2.7",
+  "version": "0.2.8",
+  "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/apps/server/go.mod

@@ -4,7 +4,7 @@ go 1.24.3
 
 require (
 	github.com/gin-gonic/gin v1.11.0
-	github.com/robsuncn/keystone v0.1.1
+	github.com/robsuncn/keystone v0.2.0
 	github.com/swaggo/files v1.0.1
 	github.com/swaggo/gin-swagger v1.6.0
 	github.com/swaggo/swag v1.16.2

package/template/apps/server/go.sum

@@ -144,6 +144,7 @@ github.com/richardlehane/msoleps v1.0.4 h1:WuESlvhX3gH2IHcd8UqyCuFY5yiq/GR/yqaSM
 github.com/richardlehane/msoleps v1.0.4/go.mod h1:BWev5JBpU9Ko2WAgmZEuiz4/u3ZYTKbjLycmwiWUfWg=
 github.com/robsuncn/keystone v0.1.1 h1:0BK2lL9wGjp9/0ZWnwoNnEHqGvAkGYLQbkwlVemDSzQ=
 github.com/robsuncn/keystone v0.1.1/go.mod h1:VPNHWG9pZi00SRC8hqy47EvfxnI795/ZC1vSkLm6x1c=
+github.com/robsuncn/keystone v0.2.0/go.mod h1:qIpuWlWXmuwy+lEuyMDLy5FLzjRWki/oJ3nGO5jyIFc=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=

package/template/apps/server/internal/modules/example/api/handler/item_handler.go

@@ -6,7 +6,9 @@ import (
 	"github.com/gin-gonic/gin"
 	hcommon "github.com/robsuncn/keystone/api/handler/common"
 	"github.com/robsuncn/keystone/api/response"
+	"github.com/robsuncn/keystone/infra/i18n"
 
+	examplei18n "__APP_NAME__/apps/server/internal/modules/example/i18n"
 	"__APP_NAME__/apps/server/internal/modules/example/domain/models"
 	"__APP_NAME__/apps/server/internal/modules/example/domain/service"
 )
@@ -38,14 +40,14 @@ const defaultTenantID uint = 1
 
 func (h *ItemHandler) List(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	items, err := h.items.List(c.Request.Context(), tenantID)
 	if err != nil {
-		response.InternalError(c, "failed to load example items")
+		response.InternalErrorI18n(c, examplei18n.MsgItemLoadFailed)
 		return
 	}
 
@@ -54,14 +56,14 @@ func (h *ItemHandler) List(c *gin.Context) {
 
 func (h *ItemHandler) Create(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	var input itemInput
 	if err := c.ShouldBindJSON(&input); err != nil {
-		response.BadRequest(c, "invalid payload")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidPayload)
 		return
 	}
 
@@ -71,36 +73,34 @@ func (h *ItemHandler) Create(c *gin.Context) {
 		Status:      input.Status,
 	})
 	if err != nil {
-		switch {
-		case errors.Is(err, service.ErrTitleRequired):
-			response.BadRequest(c, "title is required")
-		case errors.Is(err, service.ErrStatusInvalid):
-			response.BadRequest(c, "invalid status")
-		default:
-			response.InternalError(c, "failed to create example item")
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			response.BadRequestI18n(c, i18nErr.Key)
+			return
 		}
+		response.InternalErrorI18n(c, examplei18n.MsgItemCreateFailed)
 		return
 	}
 
-	response.Created(c, item)
+	response.CreatedI18n(c, examplei18n.MsgItemCreated, item)
 }
 
 func (h *ItemHandler) Update(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	id, err := hcommon.ParseUintParam(c, "id")
 	if err != nil || id == 0 {
-		response.BadRequest(c, "invalid id")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidID)
 		return
 	}
 
 	var input itemUpdateInput
 	if err := c.ShouldBindJSON(&input); err != nil {
-		response.BadRequest(c, "invalid payload")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidPayload)
 		return
 	}
 
@@ -110,45 +110,48 @@ func (h *ItemHandler) Update(c *gin.Context) {
 		Status:      input.Status,
 	})
 	if err != nil {
-		switch {
-		case errors.Is(err, service.ErrItemNotFound):
-			response.NotFound(c, "item not found")
-		case errors.Is(err, service.ErrTitleRequired):
-			response.BadRequest(c, "title is required")
-		case errors.Is(err, service.ErrStatusInvalid):
-			response.BadRequest(c, "invalid status")
-		default:
-			response.InternalError(c, "failed to update example item")
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			if i18nErr.Key == examplei18n.MsgItemNotFound {
+				response.NotFoundI18n(c, i18nErr.Key)
+			} else {
+				response.BadRequestI18n(c, i18nErr.Key)
+			}
+			return
 		}
+		response.InternalErrorI18n(c, examplei18n.MsgItemUpdateFailed)
 		return
 	}
 
-	response.SuccessWithMessage(c, "updated", item)
+	response.SuccessI18n(c, examplei18n.MsgItemUpdated, item)
 }
 
 func (h *ItemHandler) Delete(c *gin.Context) {
 	if h == nil || h.items == nil {
-		response.ServiceUnavailable(c, "example items unavailable")
+		response.ServiceUnavailableI18n(c, examplei18n.MsgServiceUnavailable)
 		return
 	}
 	tenantID := resolveTenantID(c)
 
 	id, err := hcommon.ParseUintParam(c, "id")
 	if err != nil || id == 0 {
-		response.BadRequest(c, "invalid id")
+		response.BadRequestI18n(c, examplei18n.MsgInvalidID)
 		return
 	}
 
 	if err := h.items.Delete(c.Request.Context(), tenantID, id); err != nil {
-		if errors.Is(err, service.ErrItemNotFound) {
-			response.NotFound(c, "item not found")
-			return
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			if i18nErr.Key == examplei18n.MsgItemNotFound {
+				response.NotFoundI18n(c, i18nErr.Key)
+				return
+			}
 		}
-		response.InternalError(c, "failed to delete example item")
+		response.InternalErrorI18n(c, examplei18n.MsgItemDeleteFailed)
 		return
 	}
 
-	response.SuccessWithMessage(c, "deleted", gin.H{"id": id})
+	response.SuccessI18n(c, examplei18n.MsgItemDeleted, gin.H{"id": id})
 }
 
 func resolveTenantID(c *gin.Context) uint {

package/template/apps/server/internal/modules/example/domain/service/errors.go

@@ -7,3 +7,16 @@ var (
 	ErrTitleRequired = errors.New("title is required")
 	ErrStatusInvalid = errors.New("status is invalid")
 )
+
+// I18n version (uncomment when using keystone with i18n support):
+//
+// import (
+// 	"github.com/robsuncn/keystone/infra/i18n"
+// 	examplei18n "your-app/apps/server/internal/modules/example/i18n"
+// )
+//
+// var (
+// 	ErrItemNotFound  = &i18n.I18nError{Key: examplei18n.MsgItemNotFound}
+// 	ErrTitleRequired = &i18n.I18nError{Key: examplei18n.MsgTitleRequired}
+// 	ErrStatusInvalid = &i18n.I18nError{Key: examplei18n.MsgStatusInvalid}
+// )

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

@@ -0,0 +1,16 @@
+package examplei18n
+
+import (
+	"embed"
+
+	"github.com/robsuncn/keystone/infra/i18n"
+)
+
+//go:embed locales/*.json
+var localeFS embed.FS
+
+// RegisterLocales registers the example module's locale files with the i18n system.
+// Call this during module initialization.
+func RegisterLocales() error {
+	return i18n.LoadModuleLocales(localeFS, "locales")
+}

package/template/apps/server/internal/modules/example/i18n/keys.go

@@ -0,0 +1,23 @@
+package examplei18n
+
+// Example module i18n message keys
+const (
+	// Item messages
+	MsgItemCreated      = "example.item.created"
+	MsgItemUpdated      = "example.item.updated"
+	MsgItemDeleted      = "example.item.deleted"
+	MsgItemNotFound     = "example.item.notFound"
+	MsgItemLoadFailed   = "example.item.loadFailed"
+	MsgItemCreateFailed = "example.item.createFailed"
+	MsgItemUpdateFailed = "example.item.updateFailed"
+	MsgItemDeleteFailed = "example.item.deleteFailed"
+
+	// Validation messages
+	MsgTitleRequired = "example.validation.titleRequired"
+	MsgStatusInvalid = "example.validation.statusInvalid"
+	MsgInvalidID     = "example.validation.invalidId"
+	MsgInvalidPayload = "example.validation.invalidPayload"
+
+	// Service messages
+	MsgServiceUnavailable = "example.service.unavailable"
+)

package/template/apps/server/internal/modules/example/i18n/locales/en-US.json

@@ -0,0 +1,18 @@
+{
+  "example.item.created": "Item created successfully",
+  "example.item.updated": "Item updated successfully",
+  "example.item.deleted": "Item deleted successfully",
+  "example.item.notFound": "Item not found",
+  "example.item.loadFailed": "Failed to load items",
+  "example.item.createFailed": "Failed to create item",
+  "example.item.updateFailed": "Failed to update item",
+  "example.item.deleteFailed": "Failed to delete item",
+  "example.validation.titleRequired": "Title is required",
+  "example.validation.statusInvalid": "Invalid status value",
+  "example.validation.invalidId": "Invalid ID",
+  "example.validation.invalidPayload": "Invalid request payload",
+  "example.service.unavailable": "Example service is unavailable",
+  "permission.example.item": "Example Items",
+  "permission.example.item.view": "View Items",
+  "permission.example.item.manage": "Manage Items"
+}

package/template/apps/server/internal/modules/example/i18n/locales/zh-CN.json

@@ -0,0 +1,18 @@
+{
+  "example.item.created": "项目创建成功",
+  "example.item.updated": "项目更新成功",
+  "example.item.deleted": "项目删除成功",
+  "example.item.notFound": "项目不存在",
+  "example.item.loadFailed": "加载项目列表失败",
+  "example.item.createFailed": "创建项目失败",
+  "example.item.updateFailed": "更新项目失败",
+  "example.item.deleteFailed": "删除项目失败",
+  "example.validation.titleRequired": "标题不能为空",
+  "example.validation.statusInvalid": "状态值无效",
+  "example.validation.invalidId": "无效的 ID",
+  "example.validation.invalidPayload": "请求参数无效",
+  "example.service.unavailable": "示例服务暂不可用",
+  "permission.example.item": "示例项目",
+  "permission.example.item.view": "查看项目",
+  "permission.example.item.manage": "管理项目"
+}

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`。

package/template/docs/I18N.md

@@ -0,0 +1,319 @@
+# Keystone i18n Guide
+
+This guide explains how to use internationalization (i18n) in your Keystone application.
+
+## Overview
+
+Keystone provides built-in i18n support for both frontend and backend:
+- **Frontend**: Uses `react-i18next` with automatic language detection
+- **Backend**: Uses `go-i18n` with Accept-Language header parsing
+
+Supported languages:
+- Chinese Simplified (zh-CN) - Default
+- English (en-US)
+
+## Configuration
+
+### Enable i18n
+
+i18n is enabled by default in `app.config.ts`:
+
+```typescript
+export const appConfig: Partial<KeystoneWebConfig> = {
+  ui: {
+    i18n: {
+      enabled: true,
+      defaultLocale: 'zh-CN',
+      supportedLocales: ['zh-CN', 'en-US'],
+    },
+  },
+}
+```
+
+## Frontend Usage
+
+### Basic Usage
+
+Use the `useTranslation` hook in components:
+
+```tsx
+import { useTranslation } from 'react-i18next'
+
+function MyComponent() {
+  const { t } = useTranslation('myModule')  // Namespace
+  const { t: tc } = useTranslation('common') // Common namespace
+
+  return (
+    <div>
+      <h1>{t('page.title')}</h1>
+      <Button>{tc('actions.save')}</Button>
+    </div>
+  )
+}
+```
+
+### Namespaces
+
+| Namespace | Description | Example Keys |
+|-----------|-------------|--------------|
+| `common` | Shared UI elements | `actions.save`, `messages.success` |
+| `auth` | Authentication | `login.title`, `logout.success` |
+| `system` | System management | `users.table.name` |
+| `validation` | Form validation | `required`, `email.invalid` |
+
+### Module Locale Files
+
+Create locale files in your module:
+
+```
+modules/my-module/
+├── locales/
+│   ├── zh-CN/
+│   │   └── myModule.json
+│   └── en-US/
+│       └── myModule.json
+└── index.ts
+```
+
+Example `myModule.json`:
+
+```json
+{
+  "menu": {
+    "title": "My Module"
+  },
+  "page": {
+    "title": "Page Title",
+    "createButton": "Create"
+  },
+  "table": {
+    "name": "Name",
+    "status": "Status"
+  },
+  "messages": {
+    "createSuccess": "Created successfully",
+    "deleteSuccess": "Deleted successfully"
+  }
+}
+```
+
+### Register Module Locales
+
+In your module's `index.ts`:
+
+```typescript
+import { registerModule, loadModuleLocales } from '@robsun/keystone-web-core'
+import { myRoutes } from './routes'
+
+// Load module i18n translations
+loadModuleLocales('myModule', {
+  'zh-CN': () => import('./locales/zh-CN/myModule.json'),
+  'en-US': () => import('./locales/en-US/myModule.json'),
+})
+
+registerModule({ name: 'my-module', routes: myRoutes })
+```
+
+### Route Labels
+
+Use `labelKey` for menu and breadcrumb labels:
+
+```tsx
+export const myRoutes: RouteObject[] = [
+  {
+    path: 'my-page',
+    element: <MyPage />,
+    handle: {
+      menu: {
+        labelKey: 'myModule:menu.title',  // i18n key
+        icon: <AppstoreOutlined />,
+      },
+      breadcrumbKey: 'myModule:menu.title',
+    },
+  },
+]
+```
+
+### Variables in Translations
+
+```json
+{
+  "greeting": "Hello, {{name}}!",
+  "itemCount": "{{count}} items"
+}
+```
+
+```tsx
+t('greeting', { name: 'John' })  // "Hello, John!"
+t('itemCount', { count: 5 })     // "5 items"
+```
+
+## Backend Usage
+
+### Response Messages
+
+Use i18n response functions in handlers:
+
+```go
+import (
+    "github.com/robsuncn/keystone/api/response"
+    "github.com/robsuncn/keystone/infra/i18n"
+)
+
+func (h *Handler) Create(c *gin.Context) {
+    // Success with translated message
+    response.CreatedI18n(c, "item.created", data)
+
+    // Error with translated message
+    response.BadRequestI18n(c, "validation.titleRequired")
+    response.NotFoundI18n(c, "item.notFound")
+    response.InternalErrorI18n(c, "item.createFailed")
+}
+```
+
+### I18n Error Type
+
+Define errors with i18n support:
+
+```go
+import (
+    "github.com/robsuncn/keystone/infra/i18n"
+    mymodulei18n "myapp/internal/modules/mymodule/i18n"
+)
+
+var (
+    ErrItemNotFound  = &i18n.I18nError{Key: mymodulei18n.MsgItemNotFound}
+    ErrTitleRequired = &i18n.I18nError{Key: mymodulei18n.MsgTitleRequired}
+)
+```
+
+Handle i18n errors in handlers:
+
+```go
+func (h *Handler) Get(c *gin.Context) {
+    item, err := h.svc.Get(ctx, id)
+    if err != nil {
+        var i18nErr *i18n.I18nError
+        if errors.As(err, &i18nErr) {
+            response.NotFoundI18n(c, i18nErr.Key)
+            return
+        }
+        response.InternalErrorI18n(c, "common.internalError")
+        return
+    }
+    response.Success(c, item)
+}
+```
+
+### Module Locale Files (Backend)
+
+Create i18n files in your module:
+
+```
+internal/modules/mymodule/
+├── i18n/
+│   ├── i18n.go         # Registration
+│   ├── keys.go         # Message key constants
+│   └── locales/
+│       ├── zh-CN.json
+│       └── en-US.json
+└── module.go
+```
+
+`keys.go`:
+
+```go
+package mymodulei18n
+
+const (
+    MsgItemCreated    = "mymodule.item.created"
+    MsgItemNotFound   = "mymodule.item.notFound"
+    MsgTitleRequired  = "mymodule.validation.titleRequired"
+)
+```
+
+`i18n.go`:
+
+```go
+package mymodulei18n
+
+import (
+    "embed"
+    "github.com/robsuncn/keystone/infra/i18n"
+)
+
+//go:embed locales/*.json
+var localeFS embed.FS
+
+func RegisterLocales() error {
+    return i18n.LoadModuleLocales(localeFS, "locales")
+}
+```
+
+Register in `module.go`:
+
+```go
+func (m *Module) RegisterI18n() error {
+    return mymodulei18n.RegisterLocales()
+}
+```
+
+### Permission Names
+
+Use `NameKey` for translatable permission names:
+
+```go
+func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
+    reg.CreateMenuI18n("mymodule:item", "My Items", "permission.mymodule.item", "mymodule", 10)
+    reg.CreateActionI18n("mymodule:item:view", "View Items", "permission.mymodule.item.view", "mymodule", "mymodule:item")
+    return nil
+}
+```
+
+## Language Switching
+
+The language switcher is automatically available in the header when i18n is enabled. Users can switch between supported languages, and:
+
+1. The UI immediately updates to the selected language
+2. All subsequent API requests include the `Accept-Language` header
+3. The language preference is persisted in localStorage
+
+## Best Practices
+
+1. **Use namespaces**: Group translations by module/feature
+2. **Common translations**: Use the `common` namespace for shared elements
+3. **Key naming**: Use dot notation for hierarchy (`page.title`, `form.nameLabel`)
+4. **Avoid concatenation**: Use variables instead of string concatenation
+5. **Default language**: Always provide Chinese (zh-CN) as the default
+6. **Consistent keys**: Use the same key structure across languages
+
+## Type Safety (Optional)
+
+Generate TypeScript types for translation keys:
+
+```bash
+pnpm generate:i18n-types
+```
+
+This creates `apps/web/src/types/i18n.d.ts` with type definitions for all your translation keys, enabling:
+- Autocomplete for translation keys in your IDE
+- Compile-time errors for invalid keys
+
+After generating types, you can use them in your components:
+
+```tsx
+import { useTranslation } from 'react-i18next'
+
+function MyComponent() {
+  const { t } = useTranslation('myModule')
+  // t('invalid.key') - TypeScript error!
+  // t('page.title') - OK with autocomplete
+}
+```
+
+## Adding a New Language
+
+1. Update `supportedLocales` in `app.config.ts`
+2. Create locale files for the new language
+3. Update backend `supportedLangs` in `infra/i18n/i18n.go`
+4. Add backend locale file in `infra/i18n/locales/`

package/template/package.json

@@ -14,6 +14,7 @@
     "clean": "node scripts/clean.js",
     "web:dev": "pnpm -C apps/web dev",
     "server:dev": "go -C apps/server run ./cmd/server",
+    "generate:i18n-types": "node scripts/generate-i18n-types.js",
     "prepare": "husky"
   },
   "devDependencies": {

package/template/scripts/generate-i18n-types.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * i18n Type Definition Generator
+ *
+ * Generates TypeScript type definitions from JSON locale files
+ * for type-safe translations in your application.
+ *
+ * Usage:
+ *   node scripts/generate-i18n-types.js
+ *
+ * Output:
+ *   apps/web/src/types/i18n.d.ts
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const rootDir = path.resolve(__dirname, '..')
+const webSrcDir = path.join(rootDir, 'apps/web/src')
+
+// Configuration
+const LOCALE_DIRS = [
+  // Platform locales from keystone-web-core (reference only, not generated)
+  // Module locales
+  path.join(webSrcDir, 'modules'),
+]
+
+const OUTPUT_FILE = path.join(webSrcDir, 'types/i18n.d.ts')
+
+/**
+ * Recursively flattens a nested object into dot-notation keys
+ */
+function flattenKeys(obj, prefix = '') {
+  const keys = []
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      keys.push(...flattenKeys(value, fullKey))
+    } else {
+      keys.push(fullKey)
+    }
+  }
+  return keys
+}
+
+/**
+ * Finds all locale JSON files in a directory
+ */
+function findLocaleFiles(dir) {
+  const files = []
+  if (!fs.existsSync(dir)) return files
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      // Look for locales directory
+      if (entry.name === 'locales') {
+        const zhDir = path.join(fullPath, 'zh-CN')
+        if (fs.existsSync(zhDir)) {
+          const jsonFiles = fs.readdirSync(zhDir).filter(f => f.endsWith('.json'))
+          for (const jsonFile of jsonFiles) {
+            files.push({
+              namespace: path.basename(jsonFile, '.json'),
+              path: path.join(zhDir, jsonFile),
+            })
+          }
+        }
+      } else {
+        files.push(...findLocaleFiles(fullPath))
+      }
+    }
+  }
+  return files
+}
+
+/**
+ * Generates TypeScript type definitions
+ */
+function generateTypes() {
+  const namespaces = new Map()
+
+  // Collect all locale files
+  for (const localeDir of LOCALE_DIRS) {
+    const files = findLocaleFiles(localeDir)
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(file.path, 'utf-8')
+        const json = JSON.parse(content)
+        const keys = flattenKeys(json)
+        namespaces.set(file.namespace, keys)
+      } catch (err) {
+        console.warn(`Warning: Could not parse ${file.path}:`, err.message)
+      }
+    }
+  }
+
+  if (namespaces.size === 0) {
+    console.log('No locale files found. Skipping type generation.')
+    return
+  }
+
+  // Generate TypeScript content
+  let output = `// Auto-generated by scripts/generate-i18n-types.js
+// Do not edit manually
+
+import 'react-i18next'
+
+declare module 'react-i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'common'
+    resources: {
+`
+
+  for (const [namespace, keys] of namespaces) {
+    output += `      ${namespace}: {\n`
+    for (const key of keys) {
+      // Create nested type from dot notation
+      output += `        '${key}': string\n`
+    }
+    output += `      }\n`
+  }
+
+  output += `    }
+  }
+}
+
+// Type-safe translation keys
+`
+
+  for (const [namespace, keys] of namespaces) {
+    const typeName = namespace.charAt(0).toUpperCase() + namespace.slice(1) + 'Keys'
+    output += `export type ${typeName} = \n`
+    output += keys.map(k => `  | '${k}'`).join('\n')
+    output += '\n\n'
+  }
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(OUTPUT_FILE)
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true })
+  }
+
+  // Write output file
+  fs.writeFileSync(OUTPUT_FILE, output, 'utf-8')
+  console.log(`Generated i18n types: ${OUTPUT_FILE}`)
+  console.log(`Namespaces: ${[...namespaces.keys()].join(', ')}`)
+}
+
+// Run generator
+generateTypes()