Cursor rule

1---
2description: CodeSpirit 多语言国际化规范 - 资源文件、本地化、前后端多语言支持
3globs: 
4  - "*Dto.cs"
5  - "**/Dtos/**/*.cs"
6  - "*Enum.cs"
7  - "**/Enums/**/*.cs"
8  - "*Controller.cs"
9  - "**/Controllers/**/*.cs"
10  - "**/Resources/**/*.cs"
11alwaysApply: false
12---
13 
14# 多语言国际化规范
15 
16## 支持语言
17- **简体中文** (zh-CN) - 默认语言
18- **英文** (en)
19 
20## 资源文件命名规范
21 
22### 共享资源
23```
24CodeSpirit.Localization/Resources/
25  ├── SharedResources.cs              # 资源类
26  ├── Shared.resx                     # 中文（默认）
27  ├── Shared.en.resx                  # 英文
28  ├── Display.resx / Display.en.resx  # 显示文本资源
29  ├── Validation.resx / Validation.en.resx  # 验证消息资源
30```
31 
32### 服务特定资源
33```
34CodeSpirit.ExamApi/Resources/
35  ├── ExamDisplayResources.cs         # 资源类
36  ├── ExamDisplay.resx                # 中文（默认）
37  └── ExamDisplay.en.resx             # 英文
38```
39 
40## 资源键命名规范
41- **通用**: `Common.{Key}` (如 `Common.Save`, `Common.Delete`)
42- **错误**: `Errors.{Key}` (如 `Errors.NotFound`, `Errors.InvalidInput`)
43- **验证**: `Validation.{Rule}` (如 `Validation.Required`, `Validation.StringLengthMax`)
44- **DTO描述**: `{EntityName}.{PropertyName}.Description` (如 `Question.Content.Description`)
45 
46示例资源文件（Display.resx）：
47```xml
48<data name="Common.Save" xml:space="preserve">
49  <value>保存</value>
50</data>
51<data name="Common.Delete" xml:space="preserve">
52  <value>删除</value>
53</data>
54<data name="Question.Content.Description" xml:space="preserve">
55  <value>请输入题目的具体内容</value>
56</data>
57```
58 
59## Controller 中使用本地化
60 
61```csharp
62using CodeSpirit.Localization.Resources;
63using Microsoft.Extensions.Localization;
64 
65public class QuestionsController : ApiControllerBase
66{
67    private readonly IStringLocalizer<SharedResources> _localizer;
68    
69    public QuestionsController(IStringLocalizer<SharedResources> localizer)
70    {
71        _localizer = localizer;
72    }
73    
74    [HttpPost]
75    public async Task<ActionResult<ApiResponse>> Create(CreateQuestionDto dto)
76    {
77        await _service.CreateAsync(dto);
78        return SuccessResponse(message: _localizer["Common.Save"].Value);
79    }
80}
81```
82 
83## DTO 验证特性多语言
84 
85### Display 特性
86```csharp
87using CodeSpirit.Localization.Resources;
88 
89public class CreateQuestionDto
90{
91    [Display(Name = "Content", ResourceType = typeof(DisplayResources))]
92    [Required(ErrorMessageResourceType = typeof(ValidationResources), 
93             ErrorMessageResourceName = "Required")]
94    [StringLength(2000, 
95        ErrorMessageResourceType = typeof(ValidationResources),
96        ErrorMessageResourceName = "StringLengthMax")]
97    public string Content { get; set; } = string.Empty;
98    
99    [Display(Name = "Score", ResourceType = typeof(DisplayResources))]
100    [Range(0, 100, 
101        ErrorMessageResourceType = typeof(ValidationResources),
102        ErrorMessageResourceName = "Range")]
103    public decimal Score { get; set; }
104}
105```
106 
107### 描述信息多语言
108```csharp
109using CodeSpirit.Localization.Attributes;
110 
111public class CreateQuestionDto
112{
113    [Display(Name = "Content", ResourceType = typeof(DisplayResources))]
114    [LocalizedDescription("Question.Content.Description", typeof(ExamDisplayResources))]
115    public string Content { get; set; } = string.Empty;
116}
117```
118 
119## 本地化异常
120 
121```csharp
122// 使用资源键
123throw new BusinessException("Errors.InvalidStartTime");
124 
125// 带参数（使用占位符 {0}, {1}）
126throw new ValidationException("Errors.NotFound", resourceId);
127```
128 
129资源文件定义：
130```xml
131<data name="Errors.NotFound" xml:space="preserve">
132  <value>资源 {0} 未找到</value>
133</data>
134```
135 
136## 枚举多语言
137```csharp
138public enum QuestionType
139{
140    [Display(Name = "SingleChoice", ResourceType = typeof(DisplayResources))]
141    SingleChoice = 1,
142    
143    [Display(Name = "MultipleChoice", ResourceType = typeof(DisplayResources))]
144    MultipleChoice = 2,
145    
146    [Display(Name = "TrueFalse", ResourceType = typeof(DisplayResources))]
147    TrueFalse = 3
148}
149```
150 
151资源文件：
152```xml
153<data name="SingleChoice" xml:space="preserve">
154  <value>单选题</value>
155</data>
156<data name="MultipleChoice" xml:space="preserve">
157  <value>多选题</value>
158</data>
159```
160 
161## 注意事项
162 
163### 强制要求（必须遵守）
164- ✅ 所有面向用户的文本必须支持多语言
165- ✅ 资源文件必须同时提供中文和英文版本
166- ✅ 验证消息、异常消息全部使用本地化
167 
168### 最佳实践（推荐遵守）
169- 💡 新开发的 DTO、枚举、控制器应使用多语言写法
170- 💡 逐步迁移现有硬编码文本到资源文件
171- 💡 定期检查资源文件是否有缺失的翻译
172 
173### 迁移指南
174对于现有代码，建议采用渐进式迁移：
1751. 新功能必须使用多语言写法
1762. 修改现有功能时，同步迁移为多语言写法
1773. 定期批量迁移高频使用的文本
178 
179