---
description: Translation guidelines for NOWCRM
alwaysApply: false
---
# Translation Guidelines

## Internationalization (i18n) Overview

### Supported Languages
- English (en) - Primary language
- French (fr) - Secondary language
- Italian (it) - Secondary language
- German (de) - Secondary language

### i18n Architecture
- Use next-intl for React components
- Store translations in JSON files
- Implement namespace-based organization
- Support for interpolation and pluralization

## File Structure

### Translation Files
```
/apps/nowcrm/messages/
├── en.json                   # English translations
├── fr.json                   # French translations
├── de.json                   # German translations
└── it.json                   # Italian translations
```

### Translation Keys
- Use nested objects for organization
- Follow consistent naming patterns
- Include context in key names
  ```json
  {
    "auth": {
      "login": {
        "title": "Sign In",
        "email": "Email Address",
        "password": "Password",
        "submit": "Sign In",
        "forgotPassword": "Forgot Password?"
      },
      "register": {
        "title": "Create Account",
        "confirmPassword": "Confirm Password"
      }
    }
  }
  ```

## Translation Implementation

### React Components
- Specify namespaces for better organization
- Handle loading states properly

#### Server Components

```ts
import { getTranslations } from 'next-intl';

export default async function ContactsPage() {
  const t = await getTranslations('Contacts');
  return (
    <main>
      <h1>{t('contacts.header')}</h1>
      {/* … */}
    </main>
  );
}
```

#### Client Components

```tsx
'use client';
import { useTranslations } from 'next-intl';

export default function LoginForm() {
  const t = useTranslations('auth');

  return (
    <form>
      <h1>{t('login.title')}</h1>
      <input placeholder={t('login.email')} type="email" />
      <input placeholder={t('login.password')} type="password" />
      <button type="submit">{t('login.submit')}</button>
    </form>
  );
}
```

### Interpolation
- Use interpolation for dynamic content
- Pass variables through t() function
- Keep interpolation simple and readable
  ```typescript
  // ✅ Correct
  const WelcomeMessage = ({ userName }: { userName: string }) => {
    const { t } = useTranslations('common');

    return (
      <h1>{t('welcome.message', { name: userName })}</h1>
    );
  };

  // Translation file
  {
    "welcome": {
      "message": "Welcome back, {{name}}!"
    }
  }
  ```

### Pluralization
- Handle singular/plural forms correctly
- Use count-based pluralization
- Support different plural rules per language
  ```typescript
  // ✅ Correct
  const ItemCount = ({ count }: { count: number }) => {
    const { t } = useTranslations('common');

    return (
      <span>{t('items.count', { count })}</span>
    );
  };

  // Translation file
  {
    "items": {
      "count_one": "{{count}} item",
      "count_other": "{{count}} items"
    }
  }
  ```

## Translation Management

### Adding New Strings
1. Add English translation first
2. Use descriptive keys that indicate context
3. Include comments for translators when needed
4. Test with long translations to ensure UI flexibility
  ```json
  {
    "user": {
      "profile": {
        // Displayed in user profile header
        "displayName": "Display Name",
        // Used in forms when editing profile
        "editDisplayName": "Edit Display Name",
        // Confirmation message after profile update
        "updateSuccess": "Profile updated successfully"
      }
    }
  }
  ```

### Translation Validation
- Use TypeScript for translation key validation
- Implement automated checks for missing translations
- Validate interpolation parameters
  ```typescript
  // ✅ Correct - Type-safe translations
  type TranslationKey =
    | 'auth.login.title'
    | 'auth.login.email'
    | 'auth.login.password'
    | 'common.welcome.message';

  const t = (key: TranslationKey, options?: any) => {
    // Translation implementation
  };
  ```

## Best Practices

### Key Naming
- Use descriptive, hierarchical keys
- Avoid abbreviations
- Group related translations
- Keep keys consistent across languages
  ```json
  // ✅ Correct
  {
    "dashboard": {
      "header": {
        "title": "Dashboard",
        "subtitle": "Welcome to your workspace"
      },
      "actions": {
        "createNew": "Create New",
        "refresh": "Refresh Data",
        "export": "Export"
      }
    }
  }

  // ❌ Incorrect
  {
    "dash_title": "Dashboard",
    "newBtn": "New",
    "refreshData": "Refresh"
  }
  ```

### String Guidelines
- Write clear, concise text
- Use consistent terminology
- Consider character limits for UI elements
- Avoid concatenating translated strings
  ```json
  // ✅ Correct
  {
    "user": {
      "status": {
        "online": "Online",
        "offline": "Offline",
        "away": "Away"
      }
    }
  }

  // ❌ Incorrect - Don't concatenate
  {
    "user": {
      "statusPrefix": "User is ",
      "statusOnline": "online"
    }
  }
  ```

### Context Information
- Provide context for translators
- Include character limits when relevant
- Explain when/where text appears
- Note any technical constraints
  ```json
  {
    "button": {
      // Primary action button, max 20 characters
      "save": "Save Changes",
      // Secondary button in modal footer
      "cancel": "Cancel",
      // Destructive action, should sound cautious
      "delete": "Delete Permanently"
    }
  }
  ```

## Workflow

### Development Process
1. Develop features with English translations
2. Use placeholder keys during development
3. Finalize translation keys before feature completion
4. Add translations to all supported languages
5. Test with different language strings

### Translation Updates
1. Create translation tasks for new features
2. Provide context and screenshots to translators
3. Review translations for consistency
4. Test UI with translated strings
5. Update documentation when needed

### Quality Assurance
- Review translations in context
- Test with longest expected translations
- Verify formatting with interpolation
- Check for cultural appropriateness
- Ensure accessibility with screen readers

## Maintenance

### Regular Tasks
- Review and update outdated translations
- Check for unused translation keys
- Maintain consistency across languages
- Monitor for missing translations in new features

### Tools and Automation
- Use automated translation validation
- Implement missing translation detection
- Set up continuous integration checks
- Use translation management platforms when needed