296 lines
8.2 KiB
Markdown
296 lines
8.2 KiB
Markdown
|
# 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.
|