# 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}} {{truncate user_agent 100}} {{default action_text "Click Here"}} {{url_encode email}} ``` ### 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 ``` ## 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.