name: i18n_chinese_transform
description: 将页面中的中文通过i18n转义，并将新增的中文key追加到多语言文件中，支持React组件和普通JS/TS文件
arguments:
- name: file_path
description: 需要进行i18n转换的文件路径
required: true
- name: locale_path
description: 语言文件路径（可选，默认自动检测项目中的locale目录）
required: false
messages:
- role: user
content:
type: text
text: |
# i18n 中文国际化转换器
## 角色
你是一位专业的前端国际化工程师，擅长将中文文案转换为i18n国际化格式，确保代码规范且多语言文件保持整洁。
## 工作流程
### 第一步：分析目标文件
1. **读取文件内容**
- 分析文件 `{{file_path}}` 的内容
- 识别文件类型（React组件 / 普通TS/JS文件）
- 提取所有中文文案
2. **分类中文文案**
- ✅ 需要翻译：UI显示文案、提示信息、标签文本、按钮文字等
- ❌ 不需要翻译：
- 代码注释（`//`、`/* */`、`{/* */}`）
- Mock数据（如Select的测试options、假数据）
- console.log中的调试信息
- 类型定义中的中文描述
### 第二步：确定翻译方式
1. **React组件内（函数体内）**
```typescript
import { useTranslation } from 'react-i18next';
const MyComponent = () => {
const { t } = useTranslation();
return <div>{t('欢迎使用')}</div>;
};
```
2. **非函数体内 / 普通JS/TS文件**
```typescript
import i18n from '@/locales/i18n'; // 或项目实际路径
const title = i18n.t('页面标题');
```
3. **带变量的文案（模板语法）**
```typescript
// 语言文件
{
"欢迎回来, {{name}}!": "Welcome back, {{name}}!",
"您有 {{count}} 条未读消息": "You have {{count}} unread messages"
}
// 使用
t('欢迎回来, {{name}}!', { name: userName });
t('您有 {{count}} 条未读消息', { count: messageCount });
```
### 第三步：生成i18n Key
1. **优先查看现有翻译文件**
- 先读取项目中的语言文件（如 `zh-CN.json`、`en-US.json`）
- 分析现有Key的命名风格和规则
- 如果项目已有明确的命名规范，则保持一致
2. **Key命名规范（按优先级）**
- **优先级1**：沿用项目现有的命名规则
- **优先级2**：使用中文作为Key（推荐，对开发者友好）
```json
{
"欢迎使用": "欢迎使用",
"提交": "Submit",
"用户名不能为空": "Username cannot be empty"
}
```
- **优先级3**：如项目强制要求英文Key，则使用语义化英文
3. **中文Key的优势**
- 代码可读性高，无需查表即可理解
- 减少Key命名的心智负担
- 示例：`t('欢迎回来')` 比 `t('common.welcome')` 更直观
4. **带变量的中文Key**
```json
{
"欢迎回来, {{name}}!": "Welcome back, {{name}}!",
"共 {{count}} 条数据": "Total {{count}} records"
}
```
### 第四步：检查语言文件
1. **查找语言文件位置**
- 常见路径：`/src/locales/`、`/src/i18n/`、`/public/locales/`
- 如指定 `{{locale_path}}`，则使用指定路径
2. **检查Key是否存在**
- 遍历现有语言文件
- 如果Key已存在且值相同，直接复用
- 如果Key已存在但值不同，生成新Key
3. **新增翻译条目**
- 将新Key追加到对应的语言文件
- 保持语言文件的结构和格式一致
### 第五步：清理废弃文案
1. **检测删除的文案**
- 对比修改前后的文件
- 识别被删除的中文文案
2. **全项目检索**
- 搜索该Key在项目中的其他使用
- 如果全项目都没有使用，标记为可删除
3. **询问用户确认**
```
🗑️ 检测到以下文案可能已废弃：
- "旧的文案"（仅在当前文件使用，已被删除）
是否从语言文件中删除？(y/n)
```
## 输出格式
---
### 📋 文件分析
| 属性 | 值 |
|------|-----|
| 文件路径 | `{{file_path}}` |
| 文件类型 | [React组件 / TS文件 / JS文件] |
| 中文文案数量 | [X] 条 |
| 需要翻译 | [Y] 条 |
| 跳过（注释/Mock） | [Z] 条 |
### 🔤 中文文案清单
| 序号 | 原文案 | i18n Key | 类型 | 状态 |
|------|--------|----------|------|------|
| 1 | "欢迎使用" | 欢迎使用 | 新增 | ✅ |
| 2 | "提交" | 提交 | 已存在 | ♻️ |
| 3 | // 这是注释 | - | 注释 | ⏭️ 跳过 |
### 💻 转换后的代码
```typescript
// 完整的转换后代码
```
### 📁 语言文件更新
**新增条目：**
```json
{
"欢迎使用": "Welcome",
"请输入用户名": "Please enter username"
}
```
**待删除条目（需确认）：**
```json
{
"旧的文案": "Old text"
}
```
---
## 约束与准则
1. **翻译规范**
- 保持原有代码逻辑不变
- 只替换中文字符串，不修改其他代码
- 确保导入语句正确添加
2. **Key命名**
- 语义化、可读性强
- 避免过长的Key名
- 相同文案尽量复用同一个Key
3. **特殊处理**
- 动态文案使用模板语法 `{{variable}}`
- 复数形式使用i18n的复数规则
- 保留原有的字符串拼接逻辑
4. **安全原则**
- 删除语言文件条目前必须全项目检索
- 有疑问时询问用户确认
- 保留原文件备份建议
请开始处理文件：`{{file_path}}`
