Skip to content

Commit 333f7b3

Browse files
astandrikastandrik
committed
fix: add i18n ruleset
1 parent b9de65d commit 333f7b3

File tree

2 files changed

+178
-0
lines changed

2 files changed

+178
-0
lines changed

‎AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,24 @@ Uses BEM naming convention with `cn()` utility from `utils/cn`. Create a block f
179179
- **Parsers**: `src/utils/timeParsers/` - Time parsing utilities
180180
- **Query Utils**: `src/utils/query.ts` - SQL/YQL query helpers
181181

182+
### Internationalization (i18n)
183+
184+
All user-facing text must be internationalized using the i18n system. Follow the naming rules from `i18n-naming-ruleset.md`:
185+
186+
- **Component Structure**: Each component has an `i18n/` folder with `en.json` and `index.ts`
187+
- **Registration**: Use `registerKeysets()` with a unique component name
188+
- **Key Format**: Follow `<context>_<content>` pattern (e.g., `action_save`, `field_name`, `alert_error`)
189+
- **Context Prefixes**:
190+
- `action_` - buttons, links, menu items
191+
- `field_` - form fields, table columns
192+
- `title_` - page/section titles
193+
- `alert_` - notifications, errors
194+
- `context_` - descriptions, hints
195+
- `confirm_` - confirmation dialogs
196+
- `value_` - status values, options
197+
- **NEVER** use hardcoded strings in UI components
198+
- **ALWAYS** create i18n entries for all user-visible text
199+
182200
### Performance Considerations
183201

184202
- Tables use virtual scrolling for large datasets
@@ -202,10 +220,12 @@ Uses React Router v5 hooks (`useHistory`, `useParams`, etc.). Always validate ro
202220

203221
- **NEVER** call APIs directly - use `window.api.module.method()`
204222
- **NEVER** mutate state in RTK Query - return new objects/arrays
223+
- **NEVER** hardcode user-facing strings - use i18n
205224
- **ALWAYS** use `cn()` for classNames: `const b = cn('component-name')`
206225
- **ALWAYS** clear errors on user input
207226
- **ALWAYS** handle loading states in UI
208227
- **ALWAYS** validate route params exist before use
228+
- **ALWAYS** follow i18n naming rules from `i18n-naming-ruleset.md`
209229

210230
### Debugging Tips
211231

‎i18n-naming-ruleset.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# i18n Key Naming Ruleset for Cursor IDE
2+
3+
## Overview
4+
5+
This document provides a comprehensive ruleset for naming internationalization (i18n) keys and keysets in Cursor IDE projects. Following these conventions ensures consistency, maintainability, and clarity in multilingual applications.
6+
7+
## 1. Keyset Naming Rules
8+
9+
### 1.1 Keyset Types
10+
11+
Keysets are divided into 4 categories:
12+
13+
1. **System-wide** - Used across many sections (e.g., `common`, `common.units`, `common.operations`)
14+
2. **Section-wide** - Common within a section (e.g., `billing.common`)
15+
3. **Page-specific** - Specific to section pages (e.g., `billing.account`)
16+
4. **Reusable components** - For shared components (e.g., `logs.events`)
17+
18+
### 1.2 Keyset Naming Conventions
19+
20+
- **MUST**: Write context description for each keyset
21+
- **MUST**: Keep keysets concise (prefer `billing.budgets` over `billing.account.budgets`)
22+
- **MUST NOT**: Create keysets with only a few keys - merge with existing section keysets
23+
- **MUST NOT**: Create multiple keysets for sections/popups within the same area
24+
- **MUST NOT**: Start reusable component keysets with `component.` - use the section name instead
25+
26+
## 2. Key Naming Rules
27+
28+
### 2.1 Key Format
29+
30+
Keys follow the pattern: `<element-context>_<content-text>`
31+
32+
### 2.2 Context Prefixes
33+
34+
Use these standard context prefixes:
35+
36+
| Prefix | Usage | Example |
37+
| --------- | --------------------------------------------------- | ----------------------------------- |
38+
| `context` | Contextual information, hints, section descriptions | `context_save-up-and-service-sales` |
39+
| `alert` | System feedback, notifications, warnings | `alert_load-document-error` |
40+
| `action` | User actions: buttons, links, menu items | `action_document-view` |
41+
| `field` | Resource field names in tables, forms, overviews | `field_account-name` |
42+
| `title` | Titles of sections, pages, popups, menu items | `title_billing-section` |
43+
| `confirm` | Confirmation prompts and calls to action | `confirm_delete-resource` |
44+
| `value` | Radio button values, statuses, field values | `value_active-status` |
45+
46+
### 2.3 Key Naming Guidelines
47+
48+
- **MUST**: Make content description unambiguous and concise
49+
- **MUST**: Use hyphens to separate words in content description
50+
- **MUST NOT**: Use `label_` prefix (deprecated)
51+
- **SHOULD**: If context cannot be determined, omit the prefix
52+
53+
### 2.4 Examples
54+
55+
| Text | Key |
56+
| ----------------------------------------------------------- | --------------------------- |
57+
| Error loading document (notification title) | `alert_load-document-error` |
58+
| Report document not ready, try later (notification message) | `alert_act-not-ready-error` |
59+
| Scheduled maintenance on 12.02.2022 14:00-15:00 | `alert_planned-maintenance` |
60+
| View document (button) | `action_document-view` |
61+
62+
## 3. Technical Prefixes
63+
64+
### 3.1 Special Processing Prefixes
65+
66+
| Prefix | Purpose | Processing |
67+
| ------ | ---------------------------- | ------------------------------------ |
68+
| `raw_` | Bypass typography processing | Text displayed as-is |
69+
| `md_` | Enable markdown formatting | Supports **bold**, _italic_, [links] |
70+
71+
### 3.2 Formatting Rules
72+
73+
- **MUST NOT**: Use HTML markup in text
74+
- **MUST**: Use YFM markdown syntax for formatting
75+
- **CAN**: Add link attributes using markdown syntax:
76+
```json
77+
{
78+
"md_example-key": "Learn [more](https://example.com){target=_blank rel=\"noreferrer noopener\"}"
79+
}
80+
```
81+
82+
## 4. Character Restrictions
83+
84+
### 4.1 Allowed Characters
85+
86+
Keys must only contain characters matching this pattern:
87+
88+
```regex
89+
^[a-z0-9\u0400-\u04ff[\](){}<>!@#$%^&*~_\-−–—+='"`«»„"''"?.,:;|\\/ ₽™®©№\u00a0]*$/i
90+
```
91+
92+
This includes:
93+
94+
- Latin letters (a-z, A-Z)
95+
- Numbers (0-9)
96+
- Cyrillic letters (\u0400-\u04ff)
97+
- Common punctuation and symbols
98+
- Non-breaking space (\u00a0)
99+
- Currency symbols (₽)
100+
- Special characters (™®©№)
101+
102+
## 5. Best Practices
103+
104+
### 5.1 DO's
105+
106+
- ✅ Keep keys descriptive but concise
107+
- ✅ Group related keys in appropriate keysets
108+
- ✅ Use consistent naming patterns within a project
109+
- ✅ Document keyset context and purpose
110+
- ✅ Review existing keys before creating new ones
111+
112+
### 5.2 DON'Ts
113+
114+
- ❌ Don't create overly granular keysets
115+
- ❌ Don't duplicate keys across keysets
116+
- ❌ Don't use technical jargon in user-facing keys
117+
- ❌ Don't include implementation details in key names
118+
- ❌ Don't use special characters outside the allowed set
119+
120+
## 6. Regional Keys
121+
122+
For region-specific content, use appropriate postfixes as defined in the regional keys documentation.
123+
124+
## 7. Validation Checklist
125+
126+
Before finalizing i18n keys, verify:
127+
128+
- [ ] Key follows `<context>_<content>` format
129+
- [ ] Context prefix is from the standard list
130+
- [ ] Content description is clear and concise
131+
- [ ] Key is placed in appropriate keyset
132+
- [ ] No forbidden characters are used
133+
- [ ] Formatting prefixes (`raw_`, `md_`) are used correctly
134+
- [ ] No HTML markup in text values
135+
136+
## 8. Examples Summary
137+
138+
```json
139+
{
140+
"common": {
141+
"action_save": "Save",
142+
"action_cancel": "Cancel",
143+
"field_name": "Name",
144+
"field_description": "Description"
145+
},
146+
"billing.account": {
147+
"title_billing-overview": "Billing Overview",
148+
"alert_payment-failed": "Payment processing failed",
149+
"context_billing-help": "Manage your billing accounts and payment methods",
150+
"confirm_delete-account": "Are you sure you want to delete this account?"
151+
},
152+
"logs.events": {
153+
"field_timestamp": "Timestamp",
154+
"value_error-level": "Error",
155+
"action_filter-logs": "Filter logs"
156+
}
157+
}
158+
```

0 commit comments

Comments
 (0)