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

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:

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.

3.4 KiB Raw Blame History