# Email Templates Structure

This directory contains internationalized email templates for the Rustelo framework. Templates are organized by language and support both HTML and text formats.

## Directory Structure

```
templates/email/
├── en_/                    # English templates (default language)
│   ├── html/              # HTML email templates
│   │   ├── contact.hbs    # Contact form submission
│   │   ├── notification.hbs # General notifications
│   │   └── welcome.hbs    # Welcome email (example)
│   └── text/              # Plain text email templates
│       ├── contact.hbs    # Contact form submission
│       ├── notification.hbs # General notifications
│       └── welcome.hbs    # Welcome email (example)
├── es_/                   # Spanish templates
│   ├── html/
│   └── text/
├── fr_/                   # French templates (example)
│   ├── html/
│   └── text/
└── README.md              # This file
```

## Language Naming Convention

- Language directories must end with an underscore (`_`)
- Use ISO 639-1 language codes (e.g., `en`, `es`, `fr`, `de`)
- Examples: `en_`, `es_`, `fr_`, `de_`, `it_`, `pt_`, `ru_`, `ja_`, `ko_`, `zh_`

## Template Naming Convention

Templates are automatically registered with the naming pattern: `{language}_{template_name}_{format}`

Examples:
- `en_contact_html` - English contact form HTML template
- `es_contact_text` - Spanish contact form text template
- `fr_notification_html` - French notification HTML template

## Language Fallback

The email system provides automatic language fallback:

1. **Requested Language**: First tries the specific language (e.g., `es_contact_html`)
2. **Default Language**: Falls back to English (`en_contact_html`)
3. **Legacy Support**: Falls back to templates without language prefix (`contact_html`)

## Creating New Templates

### 1. Create Language Directory

```bash
mkdir -p templates/email/fr_/html
mkdir -p templates/email/fr_/text
```

### 2. Create Template Files

Create both HTML and text versions for each template:

```bash
# HTML version
touch templates/email/fr_/html/contact.hbs
touch templates/email/fr_/html/notification.hbs

# Text version
touch templates/email/fr_/text/contact.hbs
touch templates/email/fr_/text/notification.hbs
```

### 3. Template Content Structure

Each template should use Handlebars syntax and include appropriate variables:

**Contact Form Variables:**
- `{{name}}` - Sender's name
- `{{email}}` - Sender's email
- `{{subject}}` - Message subject
- `{{message}}` - Message content
- `{{form_type}}` - Type of form (contact, support, etc.)
- `{{submitted_at}}` - Submission timestamp
- `{{ip_address}}` - Sender's IP address (optional)
- `{{user_agent}}` - Sender's browser info (optional)
- `{{fields}}` - Additional form fields (optional)

**Notification Variables:**
- `{{title}}` - Notification title
- `{{message}}` - Notification message
- `{{content}}` - Additional content (optional)
- `{{type}}` - Notification type (info, warning, success, danger)
- `{{action_url}}` - Call-to-action URL (optional)
- `{{action_text}}` - Call-to-action text (optional)
- `{{timestamp}}` - Notification timestamp

## Available Handlebars Helpers

The email system provides several custom helpers:

### Date Formatting
```handlebars
{{date_format submitted_at "%B %d, %Y at %I:%M %p UTC"}}
{{date_format submitted_at "%d de %B de %Y a las %H:%M UTC"}}
```

### Text Manipulation
```handlebars
{{capitalize form_type}}              <!-- "contact" → "Contact" -->
{{truncate user_agent 100}}           <!-- Limit text to 100 characters -->
{{default action_text "Click Here"}}  <!-- Use default if empty -->
{{url_encode email}}                  <!-- URL encode text -->
```

### Conditional Content
```handlebars
{{#if fields}}
    Additional fields are present
{{/if}}

{{#each fields}}
    {{@key}}: {{this}}
{{/each}}
```

## Language Detection

The email system automatically detects the preferred language from:

1. **User Profile**: User's saved language preference (if authenticated)
2. **Request Headers**: `Accept-Language` HTTP header
3. **Default Fallback**: English (`en`)

### Supported Languages

The system currently supports these language codes:
- `en` - English
- `es` - Spanish
- `fr` - French
- `de` - German
- `it` - Italian
- `pt` - Portuguese
- `ru` - Russian
- `ja` - Japanese
- `ko` - Korean
- `zh` - Chinese

## Using Templates in Code

### Server-side Usage

```rust
// Send with automatic language detection
email_service.send_contact_form(
    "John Doe",
    "john@example.com",
    "Question",
    "Message content",
    "admin@app.com"
).await?;

// Send with specific language
email_service.send_contact_form_with_language(
    "Juan Pérez",
    "juan@example.com",
    "Pregunta",
    "Contenido del mensaje",
    "admin@app.com",
    "es"  // Spanish
).await?;

// Send templated email
email_service.send_templated_email_with_language(
    "user@example.com",
    "Welcome!",
    "welcome",
    template_data,
    "fr"  // French
).await?;
```

### Client-side Language

The contact and support form components automatically detect language from browser headers:

```rust
// Language is automatically detected from Accept-Language header
<ContactForm
    recipient="contact@yourapp.com"
    title="Contact Us"
/>
```

## Template Best Practices

### 1. Consistency
- Use consistent styling across all language versions
- Maintain the same structure and layout
- Keep variable names identical across languages

### 2. Cultural Considerations
- Adapt date formats for different regions
- Consider right-to-left languages if needed
- Use appropriate salutations and closings
- Respect cultural communication norms

### 3. Content Guidelines
- Keep translations accurate and natural
- Use professional tone appropriate for business communication
- Include all necessary legal disclaimers
- Test with native speakers when possible

### 4. HTML Best Practices
- Use semantic HTML structure
- Include proper `lang` attribute in HTML templates
- Ensure responsive design for mobile devices
- Use accessible color contrasts
- Include fallback fonts for different character sets

### 5. Text Templates
- Keep plain text versions readable and well-formatted
- Use appropriate line breaks and spacing
- Include all important information from HTML version
- Test rendering in various email clients

## Testing Templates

### 1. Development Testing
Use the console provider to see rendered templates:

```toml
[email]
provider = "console"
```

### 2. Language Testing
Test specific languages by setting Accept-Language header:

```bash
curl -H "Accept-Language: es-ES,es;q=0.9" \
     -X POST /api/email/contact \
     -d '{"name":"Test","email":"test@example.com","subject":"Test","message":"Test"}'
```

### 3. Template Validation
- Verify all variables are properly escaped
- Check for proper fallback behavior
- Test with various data inputs
- Validate HTML structure and accessibility

## Migration from Legacy Templates

If you have existing templates without language prefixes:

1. **Backup existing templates**
2. **Create language directories** (`en_/html/`, `en_/text/`)
3. **Move templates** to appropriate language directories
4. **Update template names** to remove language prefixes
5. **Test thoroughly** to ensure proper fallback behavior

## Configuration

Email template directory is configured in your application config:

```toml
[email]
# Template directory (relative to root_path)
template_dir = "templates/email"
```

Or via environment variable:
```bash
EMAIL_TEMPLATE_DIR=/path/to/templates/email
```

## Troubleshooting

### Template Not Found Errors
1. Check directory structure and naming convention
2. Verify template files exist and are readable
3. Check log output for specific template name being requested
4. Ensure language fallback is working properly

### Language Detection Issues
1. Verify Accept-Language header format
2. Check supported language list
3. Test with explicit language parameter
4. Review language detection logs

### Rendering Issues
1. Validate Handlebars syntax
2. Check for missing variables
3. Test with sample data
4. Verify helper function usage

For more detailed troubleshooting, see the main email system documentation.