Rustelo/templates/email/README.md

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

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:

# 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

{{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

{{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

{{#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

// 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:

// 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:

[email]
provider = "console"

2. Language Testing

Test specific languages by setting Accept-Language header:

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:

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

Or via environment variable:

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.