first commit

2026-07-13 15:23:29 +08:00
commit 50885a98c8
473 changed files with 33772 additions and 0 deletions
@@ -0,0 +1,101 @@
+# i18n Conventions
+
+Locale files must follow a consistent directory structure and naming convention. All keys are dot-separated, organized by module prefix matching the page path.
+
+## Directory Structure
+
+Locale files mirror page paths, with special directories for components and layout:
+
+```
+web/locales/zh_CN/              (en_US mirrors exactly)
+├── index.ts                    # Aggregates all modules
+├── menu.ts                     # Standalone files (no page path prefix)
+├── login.ts
+├── dashboard/                  # dashboard/*.tsx pages
+│   ├── analysis.ts
+│   ├── monitor.ts
+│   └── workplace.ts
+├── system/                     # system/*.tsx pages
+│   ├── info.ts
+│   ├── user.ts
+│   ├── rule.ts
+│   └── ...
+├── ai/                         # ai/*.tsx pages
+│   ├── chat.ts
+│   ├── conversation.ts
+│   └── agent.ts
+├── user/                       # user/*.tsx pages
+│   └── profile.ts
+├── components/                 # Shared component translations
+│   ├── xin-form.ts
+│   ├── xin-table.ts
+│   └── xin-crud.ts
+└── layout/                     # Layout translations
+    └── layout.ts
+```
+
+## Key Naming Rules
+
+### 1. Page translations follow page path
+
+The key prefix equals the page file path (without extension, `/index` dropped):
+
+| Page file | Locale file | Key prefix |
+|-----------|-------------|------------|
+| `pages/system/info.tsx` | `locales/zh_CN/system/info.ts` | `system.info` |
+| `pages/system/user.tsx` | `locales/zh_CN/system/user.ts` | `system.user` |
+| `pages/system/dict/index.tsx` | `locales/zh_CN/system/dict.ts` | `system.dict` |
+| `pages/ai/chat/index.tsx` | `locales/zh_CN/ai/chat.ts` | `ai.chat` |
+| `pages/dashboard/analysis.tsx` | `locales/zh_CN/dashboard/analysis.ts` | `dashboard.analysis` |
+
+### 2. `index.tsx` pages drop "/index"
+
+`pages/ai/chat/index.tsx` → file goes at `ai/chat.ts`, not `ai/chat/index.ts`.
+
+### 3. Components go in `components/` directory
+
+| Component | Locale file | Key prefix |
+|-----------|-------------|------------|
+| `XinForm` + sub-components | `components/xin-form.ts` | `xin.form` |
+| `XinTable` + sub-components | `components/xin-table.ts` | `xin.table` |
+| XinCrud shared keys | `components/xin-crud.ts` | `xin.crud` |
+
+### 4. Layout goes in `layout/` directory
+
+Layout translations are in `layout/layout.ts` with prefix `layout.*`.
+
+### 5. Standalone files stay at root
+
+Files without a page path prefix (like `menu.ts`, `login.ts`) stay at the root of the locale directory.
+
+## File Format
+
+```typescript
+export default {
+  // Section comment (Chinese in zh_CN, English in en_US)
+  "prefix.page.title": "页面标题",
+  "prefix.field.name": "字段名",
+  "prefix.field.name.required": "字段名为必填项",
+};
+```
+
+- **Quotes**: Always double quotes for keys and values
+- **Indentation**: 2 spaces
+- **Trailing commas**: Yes (after last entry)
+- **Comments**: Section comments in the locale's own language
+- **No `index.ts` files** inside subdirectories — only at the language root for aggregation
+
+## Registering New Files
+
+Import and spread new locale files in the language root `index.ts`:
+
+```typescript
+import moduleName from "./path/to/file";
+
+export default {
+  ...moduleName,
+  // ... other modules
+};
+```
+
+Both `zh_CN/index.ts` and `en_US/index.ts` must be updated identically.