Cursor rule

1---
2description: Translation guidelines for NOWCRM
3alwaysApply: false
4---
5# Translation Guidelines
6 
7## Internationalization (i18n) Overview
8 
9### Supported Languages
10- English (en) - Primary language
11- French (fr) - Secondary language
12- Italian (it) - Secondary language
13- German (de) - Secondary language
14 
15### i18n Architecture
16- Use next-intl for React components
17- Store translations in JSON files
18- Implement namespace-based organization
19- Support for interpolation and pluralization
20 
21## File Structure
22 
23### Translation Files
24```
25/apps/nowcrm/messages/
26├── en.json                   # English translations
27├── fr.json                   # French translations
28├── de.json                   # German translations
29└── it.json                   # Italian translations
30```
31 
32### Translation Keys
33- Use nested objects for organization
34- Follow consistent naming patterns
35- Include context in key names
36```json
37  {
38    "auth": {
39      "login": {
40        "title": "Sign In",
41        "email": "Email Address",
42        "password": "Password",
43        "submit": "Sign In",
44        "forgotPassword": "Forgot Password?"
45      },
46      "register": {
47        "title": "Create Account",
48        "confirmPassword": "Confirm Password"
49      }
50    }
51  }
52```
53 
54## Translation Implementation
55 
56### React Components
57- Specify namespaces for better organization
58- Handle loading states properly
59 
60#### Server Components
61 
62```ts
63import { getTranslations } from 'next-intl';
64 
65export default async function ContactsPage() {
66  const t = await getTranslations('Contacts');
67  return (
68    <main>
69      <h1>{t('contacts.header')}</h1>
70      {/* … */}
71    </main>
72  );
73}
74```
75 
76#### Client Components
77 
78```tsx
79'use client';
80import { useTranslations } from 'next-intl';
81 
82export default function LoginForm() {
83  const t = useTranslations('auth');
84 
85  return (
86    <form>
87      <h1>{t('login.title')}</h1>
88      <input placeholder={t('login.email')} type="email" />
89      <input placeholder={t('login.password')} type="password" />
90      <button type="submit">{t('login.submit')}</button>
91    </form>
92  );
93}
94```
95 
96### Interpolation
97- Use interpolation for dynamic content
98- Pass variables through t() function
99- Keep interpolation simple and readable
100```typescript
101  // ✅ Correct
102  const WelcomeMessage = ({ userName }: { userName: string }) => {
103    const { t } = useTranslations('common');
104 
105    return (
106      <h1>{t('welcome.message', { name: userName })}</h1>
107    );
108  };
109 
110  // Translation file
111  {
112    "welcome": {
113      "message": "Welcome back, {{name}}!"
114    }
115  }
116```
117 
118### Pluralization
119- Handle singular/plural forms correctly
120- Use count-based pluralization
121- Support different plural rules per language
122```typescript
123  // ✅ Correct
124  const ItemCount = ({ count }: { count: number }) => {
125    const { t } = useTranslations('common');
126 
127    return (
128      <span>{t('items.count', { count })}</span>
129    );
130  };
131 
132  // Translation file
133  {
134    "items": {
135      "count_one": "{{count}} item",
136      "count_other": "{{count}} items"
137    }
138  }
139```
140 
141## Translation Management
142 
143### Adding New Strings
1441. Add English translation first
1452. Use descriptive keys that indicate context
1463. Include comments for translators when needed
1474. Test with long translations to ensure UI flexibility
148```json
149  {
150    "user": {
151      "profile": {
152        // Displayed in user profile header
153        "displayName": "Display Name",
154        // Used in forms when editing profile
155        "editDisplayName": "Edit Display Name",
156        // Confirmation message after profile update
157        "updateSuccess": "Profile updated successfully"
158      }
159    }
160  }
161```
162 
163### Translation Validation
164- Use TypeScript for translation key validation
165- Implement automated checks for missing translations
166- Validate interpolation parameters
167```typescript
168  // ✅ Correct - Type-safe translations
169  type TranslationKey =
170    | 'auth.login.title'
171    | 'auth.login.email'
172    | 'auth.login.password'
173    | 'common.welcome.message';
174 
175  const t = (key: TranslationKey, options?: any) => {
176    // Translation implementation
177  };
178```
179 
180## Best Practices
181 
182### Key Naming
183- Use descriptive, hierarchical keys
184- Avoid abbreviations
185- Group related translations
186- Keep keys consistent across languages
187```json
188  // ✅ Correct
189  {
190    "dashboard": {
191      "header": {
192        "title": "Dashboard",
193        "subtitle": "Welcome to your workspace"
194      },
195      "actions": {
196        "createNew": "Create New",
197        "refresh": "Refresh Data",
198        "export": "Export"
199      }
200    }
201  }
202 
203  // ❌ Incorrect
204  {
205    "dash_title": "Dashboard",
206    "newBtn": "New",
207    "refreshData": "Refresh"
208  }
209```
210 
211### String Guidelines
212- Write clear, concise text
213- Use consistent terminology
214- Consider character limits for UI elements
215- Avoid concatenating translated strings
216```json
217  // ✅ Correct
218  {
219    "user": {
220      "status": {
221        "online": "Online",
222        "offline": "Offline",
223        "away": "Away"
224      }
225    }
226  }
227 
228  // ❌ Incorrect - Don't concatenate
229  {
230    "user": {
231      "statusPrefix": "User is ",
232      "statusOnline": "online"
233    }
234  }
235```
236 
237### Context Information
238- Provide context for translators
239- Include character limits when relevant
240- Explain when/where text appears
241- Note any technical constraints
242```json
243  {
244    "button": {
245      // Primary action button, max 20 characters
246      "save": "Save Changes",
247      // Secondary button in modal footer
248      "cancel": "Cancel",
249      // Destructive action, should sound cautious
250      "delete": "Delete Permanently"
251    }
252  }
253```
254 
255## Workflow
256 
257### Development Process
2581. Develop features with English translations
2592. Use placeholder keys during development
2603. Finalize translation keys before feature completion
2614. Add translations to all supported languages
2625. Test with different language strings
263 
264### Translation Updates
2651. Create translation tasks for new features
2662. Provide context and screenshots to translators
2673. Review translations for consistency
2684. Test UI with translated strings
2695. Update documentation when needed
270 
271### Quality Assurance
272- Review translations in context
273- Test with longest expected translations
274- Verify formatting with interpolation
275- Check for cultural appropriateness
276- Ensure accessibility with screen readers
277 
278## Maintenance
279 
280### Regular Tasks
281- Review and update outdated translations
282- Check for unused translation keys
283- Maintain consistency across languages
284- Monitor for missing translations in new features
285 
286### Tools and Automation
287- Use automated translation validation
288- Implement missing translation detection
289- Set up continuous integration checks
290- Use translation management platforms when needed