Dev doc I18N_FLUENT_TEMPLATES_GUIDE.md

docs/I18N_FLUENT_TEMPLATES_GUIDE.md

···
+# Smokesignal i18n with Fluent-Templates: Complete Developer Guide
+
+**Project**: smokesignal (Event & RSVP Management)  
+**Date**: June 1, 2025  
+**Architecture**: fluent-templates with static loading  
+**Status**: Production Ready ✅
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Architecture](#architecture)
+3. [Getting Started](#getting-started)
+4. [Creating and Managing Locales](#creating-and-managing-locales)
+5. [Creating New Templates and Routes](#creating-new-templates-and-routes)
+6. [Template Development](#template-development)
+7. [Debugging and Testing](#debugging-and-testing)
+8. [Best Practices](#best-practices)
+9. [Troubleshooting](#troubleshooting)
+10. [Performance Considerations](#performance-considerations)
+11. [Production Deployment](#production-deployment)
+
+---
+
+## Overview
+
+Smokesignal uses **fluent-templates** for internationalization (i18n), providing:
+
+- **Static Loading**: Zero runtime overhead with compile-time resource loading
+- **Automatic Fallbacks**: English fallback for missing translations
+- **Gender-Aware**: Full French Canadian gender variant support
+- **HTMX Integration**: Smart template selection for partial updates
+- **Template Functions**: Direct i18n access in templates via `tr()`, `current_locale()`, etc.
+
+### Supported Languages
+
+- **English (US)**: `en-us` (primary)
+- **French Canadian**: `fr-ca` (with gender support)
+
+### Key Features
+
+- ✅ Compile-time translation validation
+- ✅ Gender-aware translations (French)
+- ✅ HTMX partial template support
+- ✅ Automatic template fallbacks
+- ✅ Comprehensive debugging tools
+- ✅ Professional translation quality
+
+---
+
+## Architecture
+
+### Core Components
+
+```
+src/i18n/
+├── mod.rs                  # Main i18n exports and compatibility
+├── fluent_loader.rs        # Static loader and core functions
+├── template_helpers.rs     # Template function integration
+├── gender.rs              # Gender context for translations
+└── errors.rs              # I18n error types
+
+src/http/
+├── template_renderer.rs    # Unified template rendering system
+├── middleware_i18n.rs     # Language detection middleware
+└── context.rs             # Web context with i18n support
+
+i18n/
+├── en-us/                 # English translations
+│   ├── actions.ftl        # Action buttons and commands
+│   ├── common.ftl         # Common UI elements
+│   ├── forms.ftl          # Form-related translations
+│   ├── ui.ftl             # Page-specific UI content
+│   └── errors.ftl         # Error messages
+└── fr-ca/                 # French Canadian translations
+    ├── actions.ftl        # (Same structure as English)
+    ├── common.ftl
+    ├── forms.ftl
+    ├── ui.ftl
+    └── errors.ftl
+```
+
+### Static Loader Configuration
+
+```rust
+// src/i18n/fluent_loader.rs
+static_loader! {
+    pub static LOCALES = {
+        locales: "./i18n",              // Path to translation files
+        fallback_language: "en-us",     // Default language
+        customise: |bundle| {
+            bundle.set_use_isolating(false);  // Clean output
+        },
+    };
+}
+```
+
+### Template Integration
+
+```rust
+// Templates have direct access to i18n functions
+{{ tr("welcome-message") }}                    // Basic translation
+{{ tr("user-count", count=users|length) }}     // With parameters
+{{ tr("welcome-user", gender=user_gender) }}   // Gender-aware (French)
+{{ current_locale() }}                         // Current language
+{{ has_locale("fr-ca") }}                     // Language availability check
+```
+
+---
+
+## Getting Started
+
+### 1. Development Setup
+
+```bash
+# Build the project (includes i18n validation)
+cargo build
+
+# Run i18n tests
+cargo test i18n
+
+# Run comprehensive i18n testing tool
+cargo run --bin i18n-tester
+
+# Check for FTL duplicate keys
+./utils/find_ftl_duplicates.sh
+```
+
+### 2. Basic Workflow
+
+1. **Add Translation Keys**: Update `.ftl` files in both locales
+2. **Update Templates**: Use `tr()` functions in templates
+3. **Test**: Run i18n testing tools
+4. **Build**: Compile to validate all translations
+5. **Deploy**: Static loading means zero runtime overhead
+
+### 3. Project Structure
+
+```
+smokesignal/
+├── i18n/                    # Translation files
+├── src/i18n/               # I18n system code
+├── templates/              # Jinja2 templates with i18n
+├── utils/                  # FTL debugging scripts
+└── docs/                   # This documentation
+```
+
+---
+
+## Creating and Managing Locales
+
+### Adding a New Language
+
+#### Step 1: Create Directory Structure
+
+```bash
+# Create new locale directory (example: Spanish)
+mkdir -p i18n/es-es
+
+# Copy English files as templates
+cp i18n/en-us/*.ftl i18n/es-es/
+```
+
+#### Step 2: Update Supported Languages
+
+```rust
+// src/i18n/fluent_loader.rs
+pub const SUPPORTED_LANGUAGES: &[&str] = &[
+    "en-us", 
+    "fr-ca", 
+    "es-es"  // Add new language
+];
+```
+
+#### Step 3: Translate Content
+
+Edit each `.ftl` file in the new locale directory:
+
+```fluent
+# i18n/es-es/ui.ftl
+homepage-title = Señal de Humo
+homepage-subtitle = Encuentra eventos, haz conexiones y crea comunidad.
+
+# With parameters
+user-count = { $count ->
+    [one] { $count } usuario
+   *[other] { $count } usuarios
+}
+
+# Gender-aware (if needed)
+welcome-user = { $gender ->
+    [masculine] Bienvenido { $name }
+    [feminine] Bienvenida { $name }
+   *[other] Bienvenido/a { $name }
+}
+```
+
+#### Step 4: Create Templates (Optional)
+
+```bash
+# Create language-specific templates
+cp templates/home.en-us.html templates/home.es-es.html
+cp templates/home.en-us.partial.html templates/home.es-es.partial.html
+cp templates/home.en-us.bare.html templates/home.es-es.bare.html
+```
+
+#### Step 5: Test New Locale
+
+```bash
+# Comprehensive testing
+cargo run --bin i18n-tester
+
+# Check for issues
+cargo test test_new_locale_integration
+
+# Validate no duplicates
+./utils/find_ftl_duplicates.sh
+```
+
+### Managing Gender Support
+
+For languages requiring gender agreement (like French):
+
+```fluent
+# Gender-aware translations in fr-ca/ui.ftl
+welcome-message = { $gender ->
+    [masculine] Bienvenue { $name }, vous êtes connecté
+    [feminine] Bienvenue { $name }, vous êtes connectée
+   *[other] Bienvenue { $name }, vous êtes connecté·e
+}
+
+status-active = { $gender ->
+    [masculine] Actif
+    [feminine] Active
+   *[other] Actif/Active
+}
+```
+
+### File Organization
+
+#### Translation Key Prefixes
+
+- `ui-*`: User interface elements (buttons, labels, navigation)
+- `form-*`: Form labels, placeholders, validation messages  
+- `error-*`: Error messages and alerts
+- `action-*`: Action buttons and links
+- `page-*`: Page titles and headings
+- `admin-*`: Admin interface specific
+- `event-*`: Event-related content
+- `rsvp-*`: RSVP-related content
+
+#### File Structure
+
+```
+actions.ftl     # Action buttons (save, edit, delete, etc.)
+common.ftl      # Common UI elements (navigation, headers)
+forms.ftl       # Form-related translations
+ui.ftl          # Page-specific UI content
+errors.ftl      # Error messages and validation
+```
+
+---
+
+## Creating New Templates and Routes
+
+### 1. Planning Your New Page
+
+Before creating templates and routes, plan your page structure:
+
+```
+New Page: Event Analytics Dashboard
+├── Route: /analytics/{handle_slug}/{event_rkey}
+├── Handler: handle_analytics_dashboard
+├── Templates: 
+│   ├── analytics.en-us.html (full page)
+│   ├── analytics.en-us.bare.html (HTMX boosted)
+│   ├── analytics.en-us.partial.html (HTMX partial)
+│   ├── analytics.fr-ca.html (French full page)
+│   ├── analytics.fr-ca.bare.html (French boosted)
+│   └── analytics.fr-ca.partial.html (French partial)
+└── Translation Keys:
+    ├── page-title-analytics
+    ├── analytics-*
+    └── chart-*
+```
+
+### 2. Add Translation Keys
+
+First, add all required translation keys to both locales:
+
+```fluent
+# i18n/en-us/ui.ftl
+page-title-analytics = Event Analytics Dashboard
+analytics-overview = Analytics Overview
+analytics-attendees = Attendee Statistics
+analytics-timeline = Event Timeline
+chart-rsvp-trends = RSVP Trends
+chart-attendance-forecast = Attendance Forecast
+analytics-export = Export Data
+analytics-date-range = Date Range
+analytics-no-data = No analytics data available for this event
+```
+
+```fluent
+# i18n/fr-ca/ui.ftl
+page-title-analytics = Tableau de Bord Analytique
+analytics-overview = Aperçu Analytique
+analytics-attendees = Statistiques des Participants
+analytics-timeline = Chronologie de l'Événement
+chart-rsvp-trends = Tendances RSVP
+chart-attendance-forecast = Prévision de Participation
+analytics-export = Exporter les Données
+analytics-date-range = Plage de Dates
+analytics-no-data = Aucune donnée analytique disponible pour cet événement
+```
+
+### 3. Create the Route Handler
+
+```rust
+// src/http/handle_analytics_dashboard.rs
+use axum::{
+    extract::{Path, State},
+    response::Response,
+};
+use axum_htmx::HxRequest;
+use headers::HeaderMap;
+use minijinja::context as template_context;
+
+use crate::{
+    http::{
+        context::WebContext,
+        middleware_i18n::Language,
+        template_renderer::TemplateRenderer,
+    },
+    i18n::gender::Gender,
+};
+
+pub async fn handle_analytics_dashboard(
+    State(web_context): State<WebContext>,
+    Path((handle_slug, event_rkey)): Path<(String, String)>,
+    language: Language,
+    HxRequest(hx_request): HxRequest,
+    headers: HeaderMap,
+) -> Response {
+    // Extract HTMX context
+    let hx_boosted = headers.get("hx-boosted").is_some();
+    
+    // Create renderer with context
+    let renderer = TemplateRenderer::new(
+        web_context,
+        language,
+        None, // TODO: Extract user gender from session
+        hx_boosted,
+        hx_request,
+    );
+
+    // TODO: Fetch analytics data from database
+    let analytics_data = fetch_event_analytics(&handle_slug, &event_rkey).await;
+    
+    match analytics_data {
+        Ok(data) => {
+            let template_context = template_context! {
+                handle_slug => handle_slug,
+                event_rkey => event_rkey,
+                analytics => data,
+                chart_data => prepare_chart_data(&data),
+            };
+            
+            renderer.render_template(
+                "analytics",
+                template_context,
+                Some(&handle_slug),
+                &format!("/analytics/{}/{}", handle_slug, event_rkey),
+            )
+        }
+        Err(err) => {
+            renderer.render_error(
+                format!("Failed to load analytics: {}", err),
+                template_context! {
+                    handle_slug => handle_slug,
+                    event_rkey => event_rkey,
+                }
+            )
+        }
+    }
+}
+
+async fn fetch_event_analytics(handle_slug: &str, event_rkey: &str) -> Result<AnalyticsData, AnalyticsError> {
+    // TODO: Implement database queries for analytics
+    todo!("Implement analytics data fetching")
+}
+
+fn prepare_chart_data(analytics: &AnalyticsData) -> ChartData {
+    // TODO: Transform analytics data for frontend charts
+    todo!("Implement chart data preparation")
+}
+```
+
+### 4. Add Route to Server
+
+```rust
+// src/http/server.rs
+use crate::http::handle_analytics_dashboard::handle_analytics_dashboard;
+
+pub fn build_router(web_context: WebContext) -> Router {
+    Router::new()
+        // ...existing routes...
+        .route("/analytics/{handle_slug}/{event_rkey}", get(handle_analytics_dashboard))
+        // ...rest of routes...
+        .with_state(web_context.clone())
+}
+```
+
+### 5. Create Template Files
+
+#### Full Page Template
+
+```html
+<!-- templates/analytics.en-us.html -->
+{% extends "base.en-us.html" %}
+
+{% block title %}{{ tr("page-title-analytics") }}{% endblock %}
+
+{% block content %}
+<div class="analytics-dashboard">
+    <header class="analytics-header">
+        <h1>{{ tr("analytics-overview") }}</h1>
+        <div class="analytics-controls">
+            <select name="date_range" hx-get="/analytics/{{ handle_slug }}/{{ event_rkey }}" 
+                    hx-target="#analytics-content" hx-trigger="change">
+                <option value="7d">{{ tr("analytics-date-range") }}: 7 {{ tr("common-days") }}</option>
+                <option value="30d">{{ tr("analytics-date-range") }}: 30 {{ tr("common-days") }}</option>
+                <option value="all">{{ tr("common-all-time") }}</option>
+            </select>
+            <button class="btn-export" hx-get="/analytics/{{ handle_slug }}/{{ event_rkey }}/export">
+                {{ tr("analytics-export") }}
+            </button>
+        </div>
+    </header>
+
+    <main id="analytics-content">
+        {% if analytics.has_data %}
+            <section class="analytics-stats">
+                <div class="stat-card">
+                    <h3>{{ tr("analytics-attendees") }}</h3>
+                    <span class="stat-number">{{ analytics.total_rsvps }}</span>
+                </div>
+                <div class="stat-card">
+                    <h3>{{ tr("chart-attendance-forecast") }}</h3>
+                    <span class="stat-number">{{ analytics.projected_attendance }}</span>
+                </div>
+            </section>
+
+            <section class="analytics-charts">
+                <div class="chart-container">
+                    <h3>{{ tr("chart-rsvp-trends") }}</h3>
+                    <canvas id="rsvp-trends-chart" data-chart="{{ chart_data.rsvp_trends|tojson }}"></canvas>
+                </div>
+            </section>
+        {% else %}
+            <div class="no-data-message">
+                <p>{{ tr("analytics-no-data") }}</p>
+            </div>
+        {% endif %}
+    </main>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script src="/static/js/analytics-charts.js"></script>
+{% endblock %}
+```
+
+#### HTMX Partial Template
+
+```html
+<!-- templates/analytics.en-us.partial.html -->
+{% if analytics.has_data %}
+    <section class="analytics-stats">
+        <div class="stat-card">
+            <h3>{{ tr("analytics-attendees") }}</h3>
+            <span class="stat-number">{{ analytics.total_rsvps }}</span>
+        </div>
+        <div class="stat-card">
+            <h3>{{ tr("chart-attendance-forecast") }}</h3>
+            <span class="stat-number">{{ analytics.projected_attendance }}</span>
+        </div>
+    </section>
+
+    <section class="analytics-charts">
+        <div class="chart-container">
+            <h3>{{ tr("chart-rsvp-trends") }}</h3>
+            <canvas id="rsvp-trends-chart" data-chart="{{ chart_data.rsvp_trends|tojson }}"></canvas>
+        </div>
+    </section>
+{% else %}
+    <div class="no-data-message">
+        <p>{{ tr("analytics-no-data") }}</p>
+    </div>
+{% endif %}
+```
+
+#### HTMX Bare Template (Boosted Navigation)
+
+```html
+<!-- templates/analytics.en-us.bare.html -->
+<!DOCTYPE html>
+<html lang="{{ current_locale() }}">
+<head>
+    <meta charset="utf-8">
+    <title>{{ tr("page-title-analytics") }}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="/static/css/main.css">
+</head>
+<body>
+    {% include "components/analytics-dashboard.en-us.html" %}
+    <script src="/static/js/analytics-charts.js"></script>
+</body>
+</html>
+```
+
+#### French Templates
+
+Copy and adapt for French:
+
+```bash
+# Copy English templates to French
+cp templates/analytics.en-us.html templates/analytics.fr-ca.html
+cp templates/analytics.en-us.partial.html templates/analytics.fr-ca.partial.html
+cp templates/analytics.en-us.bare.html templates/analytics.fr-ca.bare.html
+
+# The content will be automatically translated via tr() functions
+# No manual editing needed unless you need French-specific layouts
+```
+
+### 6. Add Navigation Links
+
+```html
+<!-- Update navigation templates -->
+<!-- templates/components/nav.en-us.html -->
+{% if current_user.can_view_analytics %}
+    <a href="/analytics/{{ current_handle.handle }}/{{ event.rkey }}" 
+       hx-boost="true"
+       class="nav-link">
+        {{ tr("analytics-overview") }}
+    </a>
+{% endif %}
+```
+
+### 7. Test Your New Route
+
+```bash
+# Test compilation
+cargo build
+
+# Test i18n integration
+cargo run --bin i18n-tester
+
+# Test route (if server running)
+curl http://localhost:3000/analytics/testuser/testevent
+
+# Test HTMX partial
+curl -H "HX-Request: true" http://localhost:3000/analytics/testuser/testevent
+```
+
+### 8. Best Practices for New Routes
+
+#### Template Naming Convention
+
+```
+{page_name}.{locale}.{variant}.html
+
+Examples:
+- analytics.en-us.html          (Full page)
+- analytics.en-us.partial.html  (HTMX partial)
+- analytics.en-us.bare.html     (HTMX boosted)
+- analytics.fr-ca.html          (French full page)
+```
+
+#### Error Handling
+
+```rust
+// Always provide error context for i18n
+match operation_result {
+    Ok(data) => {
+        renderer.render_template("analytics", template_context, ...)
+    }
+    Err(err) => {
+        renderer.render_error(
+            format!("analytics-error: {}", err),
+            template_context! {
+                error_context => "analytics",
+                handle_slug => handle_slug,
+            }
+        )
+    }
+}
+```
+
+#### HTMX Integration
+
+```rust
+// Always extract HTMX context properly
+let hx_boosted = headers.get("hx-boosted").is_some();
+let hx_request = hx_request; // From HxRequest extractor
+
+// Create renderer with proper context
+let renderer = TemplateRenderer::new(
+    web_context,
+    language,
+    user_gender,    // Extract from session if available
+    hx_boosted,
+    hx_request,
+);
+```
+
+---
+
+## Template Development
+
+### Template Functions Available
+
+#### Basic Translation
+
+```html
+<!-- Simple translation -->
+<h1>{{ tr("page-title-analytics") }}</h1>
+
+<!-- With parameters -->
+<p>{{ tr("user-count", count=users|length) }}</p>
+
+<!-- With multiple parameters -->
+<span>{{ tr("event-date-range", start=event.start_date, end=event.end_date) }}</span>
+```
+
+#### Conditional Content
+
+```html
+<!-- Language-specific content -->
+{% if current_locale() == "fr-ca" %}
+    <div class="french-specific-content">
+        {{ tr("french-cultural-note") }}
+    </div>
+{% endif %}
+
+<!-- Feature availability -->
+{% if has_locale("es-es") %}
+    <a href="/language/es-es">Español</a>
+{% endif %}
+```
+
+#### Gender-Aware Content (French)
+
+```html
+<!-- Pass user gender for French translations -->
+<p>{{ tr("welcome-message", gender=user_gender) }}</p>
+
+<!-- Conditional gender display -->
+{% if current_locale() == "fr-ca" and user_gender %}
+    <span class="gender-specific">{{ tr("status-message", gender=user_gender) }}</span>
+{% endif %}
+```
+
+### Template Hierarchy
+
+#### Full Page (`base.html`)
+
+```html
+<!DOCTYPE html>
+<html lang="{{ current_locale() }}">
+<head>
+    <meta charset="utf-8">
+    <title>{% block title %}{{ tr("site-title") }}{% endblock %}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="/static/css/main.css">
+</head>
+<body>
+    {% include "components/header.html" %}
+    <main>
+        {% block content %}{% endblock %}
+    </main>
+    {% include "components/footer.html" %}
+    <script src="/static/js/htmx.min.js"></script>
+    {% block scripts %}{% endblock %}
+</body>
+</html>
+```
+
+#### HTMX Partial (content only)
+
+```html
+<!-- No HTML structure, just content -->
+<section class="content-update">
+    {{ tr("updated-content") }}
+    <div class="data-display">
+        <!-- Updated data here -->
+    </div>
+</section>
+```
+
+#### HTMX Bare (minimal HTML)
+
+```html
+<!DOCTYPE html>
+<html lang="{{ current_locale() }}">
+<head>
+    <meta charset="utf-8">
+    <title>{{ tr("page-title") }}</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="/static/css/main.css">
+</head>
+<body>
+    {% include "components/content.html" %}
+    <script src="/static/js/app.js"></script>
+</body>
+</html>
+```
+
+### Template Fallback System
+
+The system automatically falls back to English templates if language-specific versions don't exist:
+
+```
+Request: analytics.fr-ca.html
+1. Look for: templates/analytics.fr-ca.html
+2. If not found: templates/analytics.en-us.html (fallback)
+3. If not found: Error (base template missing)
+```
+
+---
+
+## Debugging and Testing
+
+### Built-in Testing Tools
+
+#### 1. Comprehensive i18n Tester
+
+```bash
+# Run the full i18n test suite
+cargo run --bin i18n-tester
+
+# This tests:
+# - Bundle loading
+# - Translation lookups
+# - Parameter handling
+# - Gender context
+# - Missing translations
+# - Template functions
+# - HTMX integration
+# - Language switching
+# - Fallback behavior
+```
+
+#### 2. Form Validation Tester
+
+```bash
+# Test form validation i18n integration
+cargo run --bin form-validation-tester
+
+# This tests:
+# - Form error translations
+# - HTMX partial form updates
+# - Language persistence in forms
+# - Context-aware error messages
+```
+
+#### 3. FTL Duplicate Detection
+
+```bash
+# Check for duplicate translation keys
+./utils/find_ftl_duplicates.sh
+
+# Clean up duplicates (interactive)
+./utils/clean_ftl_duplicates.sh
+```
+
+### Debugging Commands
+
+#### Validate Bundle Loading
+
+```rust
+// Add to your application startup
+use smokesignal::i18n::{validate_bundle_loading, check_for_duplicate_issues};
+
+fn main() {
+    // Initialize tracing first
+    tracing_subscriber::init();
+    
+    // Validate i18n system
+    validate_bundle_loading();
+    check_for_duplicate_issues();
+    
+    // Continue with app startup...
+}
+```
+
+#### Test Individual Translations
+
+```rust
+use smokesignal::i18n::{get_translation, LOCALES};
+use unic_langid::langid;
+
+// Test a specific translation
+let en_locale = langid!("en-us");
+let result = get_translation(&en_locale, "welcome-message", None);
+println!("Translation: {}", result);
+
+// Test with parameters
+let mut args = HashMap::new();
+args.insert("name".to_string(), FluentValue::from("Alice"));
+let result = get_translation(&en_locale, "welcome-user", Some(args));
+```
+
+### Common Debugging Scenarios
+
+#### Missing Translation
+
+**Symptoms**: Key name displayed instead of translation
+```
+Output: "welcome-message" instead of "Welcome!"
+```
+
+**Solution**:
+1. Check if key exists in `.ftl` files
+2. Verify key spelling matches exactly
+3. Run duplicate detection tools
+4. Check bundle loading logs
+
+#### Gender Context Not Working
+
+**Symptoms**: Generic translation instead of gendered version
+```
+Expected: "Bienvenue Marie, vous êtes connectée" (feminine)
+Actual: "Bienvenue Marie, vous êtes connecté" (default)
+```
+
+**Solution**:
+1. Verify gender parameter is passed correctly
+2. Check French `.ftl` file has gender variants
+3. Ensure gender context reaches template
+
+#### HTMX Language Switching
+
+**Symptoms**: HTMX requests don't maintain language
+```
+Page loads in French, HTMX updates appear in English
+```
+
+**Solution**:
+1. Verify `HX-Current-Language` header is set
+2. Check middleware_i18n language detection
+3. Ensure templates use proper `hx-headers` attributes
+
+### Testing Checklist
+
+Before deploying new i18n features:
+
+- [ ] All translation keys exist in both languages
+- [ ] No duplicate keys detected
+- [ ] i18n-tester passes all tests
+- [ ] Form validation works in both languages
+- [ ] HTMX partial updates maintain language
+- [ ] Gender context works for French
+- [ ] Template fallbacks work correctly
+- [ ] Error messages display in correct language
+- [ ] Language switching preserves page state
+
+---
+
+## Best Practices
+
+### Translation Key Naming
+
+#### Use Clear, Hierarchical Prefixes
+
+```fluent
+# Good
+page-title-analytics = Analytics Dashboard
+form-validation-email = Please enter a valid email address
+error-event-not-found = Event not found
+
+# Avoid
+analytics = Analytics Dashboard
+email = Please enter a valid email address
+not-found = Event not found
+```
+
+#### Keep Keys Short but Descriptive
+
+```fluent
+# Good
+btn-save = Save
+btn-cancel = Cancel
+modal-confirm-delete = Are you sure you want to delete this item?
+
+# Too verbose
+button-that-saves-the-current-form = Save
+button-that-cancels-the-current-operation = Cancel
+```
+
+### Parameter Usage
+
+#### Use Descriptive Parameter Names
+
+```fluent
+# Good
+user-greeting = Hello { $username }, you have { $message_count } new messages
+event-capacity = { $current_attendees } of { $max_capacity } attendees
+
+# Avoid generic names
+user-greeting = Hello { $a }, you have { $b } new messages
+```
+
+#### Handle Pluralization
+
+```fluent
+# English pluralization
+message-count = { $count ->
+    [one] { $count } message
+   *[other] { $count } messages
+}
+
+# French pluralization (more complex)
+message-count = { $count ->
+    [zero] Aucun message
+    [one] { $count } message
+   *[other] { $count } messages
+}
+```
+
+### Gender-Aware Translations
+
+#### French Gender Variants
+
+```fluent
+# User status with gender agreement
+user-status-active = { $gender ->
+    [masculine] Vous êtes actif
+    [feminine] Vous êtes active
+   *[other] Vous êtes actif·ve
+}
+
+# Past participles
+action-completed = { $gender ->
+    [masculine] { $action } terminé
+    [feminine] { $action } terminée
+   *[other] { $action } terminé·e
+}
+```
+
+#### Fallback Strategy
+
+```fluent
+# Always provide a neutral fallback
+welcome-message = { $gender ->
+    [masculine] Bienvenue { $name }
+    [feminine] Bienvenue { $name }
+   *[other] Bienvenue { $name }
+}
+```
+
+### Template Best Practices
+
+#### Consistent Template Structure
+
+```html
+<!-- Always use the same template structure -->
+{% extends "base.html" %}
+
+{% block title %}{{ tr("page-title-specific") }}{% endblock %}
+
+{% block content %}
+    <main class="page-specific">
+        <header>
+            <h1>{{ tr("page-heading") }}</h1>
+        </header>
+        <!-- Content here -->
+    </main>
+{% endblock %}
+```
+
+#### HTMX Integration
+
+```html
+<!-- Always include language in HTMX headers -->
+<div hx-get="/api/data" 
+     hx-headers='{"HX-Current-Language": "{{ current_locale() }}"}'>
+    {{ tr("loading-placeholder") }}
+</div>
+
+<!-- Use proper targeting -->
+<form hx-post="/submit" 
+      hx-target="#form-result"
+      hx-headers='{"HX-Current-Language": "{{ current_locale() }}"}'>
+    <!-- Form fields -->
+</form>
+```
+
+#### Error Handling
+
+```html
+<!-- Consistent error display -->
+{% if error_message %}
+    <div class="alert alert-error">
+        {{ tr("error-prefix") }}: {{ error_message }}
+    </div>
+{% endif %}
+```
+
+### Performance Optimization
+
+#### Minimize Template Variants
+
+```
+# Instead of creating many language-specific templates:
+templates/
+├── page.en-us.html
+├── page.fr-ca.html
+├── page.es-es.html
+└── ...
+
+# Use one template with i18n functions:
+templates/
+└── page.html (uses tr() functions)
+```
+
+#### Static Resource References
+
+```html
+<!-- Use locale in static resource paths if needed -->
+<link rel="stylesheet" href="/static/css/{{ current_locale() }}/custom.css">
+
+<!-- Or use conditional loading -->
+{% if current_locale() == "fr-ca" %}
+    <link rel="stylesheet" href="/static/css/french-typography.css">
+{% endif %}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### 1. "Translation key not found" Errors
+
+**Problem**: Keys display as-is instead of translations
+
+**Diagnosis**:
+```bash
+# Check if key exists
+grep -r "your-key-name" i18n/
+
+# Run duplicate checker
+./utils/find_ftl_duplicates.sh
+
+# Validate bundle loading
+cargo run --bin i18n-tester
+```
+
+**Solutions**:
+- Add missing keys to `.ftl` files
+- Fix typos in key names
+- Remove duplicate keys
+- Verify bundle loading succeeds
+
+#### 2. Gender Context Not Working
+
+**Problem**: French translations don't use correct gender
+
+**Diagnosis**:
+```rust
+// Add debug logging in template
+{{ tr("debug-gender", gender=user_gender) }}
+
+// Check gender parameter in handler
+println!("User gender: {:?}", user_gender);
+```
+
+**Solutions**:
+- Ensure gender is extracted from user session
+- Pass gender parameter to TemplateRenderer
+- Verify French `.ftl` has gender variants
+- Check gender parameter name matches template
+
+#### 3. HTMX Language Switching Issues
+
+**Problem**: HTMX requests lose language context
+
+**Diagnosis**:
+```bash
+# Check request headers
+curl -H "HX-Request: true" -H "HX-Current-Language: fr-ca" \
+     http://localhost:3000/your-endpoint
+```
+
+**Solutions**:
+- Add `HX-Current-Language` header to HTMX requests
+- Verify middleware_i18n processes header correctly
+- Check template renderer receives correct language
+- Ensure HTMX templates include language context
+
+#### 4. Template Fallback Not Working
+
+**Problem**: Missing language templates cause errors
+
+**Diagnosis**:
+```bash
+# Check template file existence
+ls templates/your-template.*.html
+
+# Test fallback logic
+cargo test test_template_fallback
+```
+
+**Solutions**:
+- Ensure English base templates exist
+- Check template naming convention
+- Verify fallback logic in template selection
+- Create missing base templates
+
+#### 5. Build-Time Bundle Loading Errors
+
+**Problem**: Compilation fails due to i18n issues
+
+**Diagnosis**:
+```bash
+# Build with verbose output
+cargo build --verbose
+
+# Check for FTL syntax errors
+./utils/find_ftl_duplicates.sh
+```
+
+**Solutions**:
+- Fix FTL syntax errors
+- Remove duplicate keys
+- Verify all referenced locales exist
+- Check static loader configuration
+
+### Debug Tools and Commands
+
+#### Enable Debug Logging
+
+```rust
+// Add to main.rs or test files
+use tracing_subscriber::{FmtSubscriber, EnvFilter};
+
+let subscriber = FmtSubscriber::builder()
+    .with_env_filter(EnvFilter::from_default_env().add_directive("debug".parse()?))
+    .finish();
+tracing::subscriber::set_global_default(subscriber)?;
+```
+
+#### Test Specific Translations
+
+```bash
+# Test individual keys
+cargo run --bin i18n-tester | grep "your-key-name"
+
+# Test specific locale
+RUST_LOG=debug cargo run --bin i18n-tester
+```
+
+#### Validate Bundle Health
+
+```bash
+# Comprehensive validation
+cargo run --bin i18n-tester
+
+# Check for duplicates
+./utils/find_ftl_duplicates.sh
+
+# Manual bundle inspection
+find i18n/ -name "*.ftl" -exec echo "=== {} ===" \; -exec cat {} \;
+```
+
+---
+
+## Performance Considerations
+
+### Static Loading Benefits
+
+The fluent-templates static loader provides:
+
+- **Zero Runtime Cost**: All translations loaded at compile time
+- **No File I/O**: No disk reads during request handling
+- **Memory Efficient**: Optimized bundle storage
+- **Fast Lookups**: O(1) translation lookups
+
+### Bundle Size Optimization
+
+#### Keep Translation Files Focused
+
+```fluent
+# Instead of one large file:
+# ui.ftl (2000+ lines)
+
+# Use multiple focused files:
+# actions.ftl (50 lines)
+# forms.ftl (100 lines)
+# errors.ftl (75 lines)
+```
+
+#### Remove Unused Translations
+
+```bash
+# Find potentially unused keys
+grep -r "tr(" templates/ | grep -o "tr([\"'][^\"']*[\"'])" | sort | uniq > used_keys.txt
+find i18n/ -name "*.ftl" -exec grep -o "^[a-zA-Z][a-zA-Z0-9_-]*" {} \; | sort | uniq > all_keys.txt
+comm -23 all_keys.txt used_keys.txt  # Keys in FTL but not used in templates
+```
+
+### Template Performance
+
+#### Minimize Template Variants
+
+Use i18n functions instead of duplicate templates:
+
+```html
+<!-- Instead of separate templates per language -->
+<!-- Good: One template with i18n -->
+<h1>{{ tr("page-title") }}</h1>
+<p>{{ tr("page-description") }}</p>
+
+<!-- Avoid: Separate templates -->
+<!-- page.en-us.html: <h1>Dashboard</h1> -->
+<!-- page.fr-ca.html: <h1>Tableau de Bord</h1> -->
+```
+
+#### Cache Template Compilation
+
+The TemplateRenderer automatically handles template caching:
+
+```rust
+// Templates are compiled once and cached
+let renderer = TemplateRenderer::new(web_context, language, gender, hx_boosted, hx_request);
+// Subsequent renders use cached compiled templates
+```
+
+### HTMX Optimization
+
+#### Minimize Partial Template Size
+
+```html
+<!-- Good: Small, focused partials -->
+<div id="user-count">{{ tr("user-count", count=users|length) }}</div>
+
+<!-- Avoid: Large partials that re-render everything -->
+<div id="entire-dashboard">
+    <!-- Hundreds of lines -->
+</div>
+```
+
+#### Language Header Efficiency
+
+```html
+<!-- Set once, reuse for all HTMX requests -->
+<div hx-headers='{"HX-Current-Language": "{{ current_locale() }}"}'>
+    <!-- All child HTMX requests inherit language -->
+</div>
+```
+
+---
+
+## Production Deployment
+
+### Pre-Deployment Checklist
+
+#### 1. Translation Completeness
+
+```bash
+# Verify all keys exist in all locales
+cargo run --bin i18n-tester | grep -i "missing\|error"
+
+# Check for duplicate keys
+./utils/find_ftl_duplicates.sh
+```
+
+#### 2. Template Coverage
+
+```bash
+# Verify all required templates exist
+find templates/ -name "*.en-us.html" | while read f; do
+    base=$(basename "$f" .en-us.html)
+    if [ ! -f "templates/${base}.fr-ca.html" ]; then
+        echo "Missing French template: ${base}.fr-ca.html"
+    fi
+done
+```
+
+#### 3. Build Validation
+
+```bash
+# Clean build to verify all i18n resources
+cargo clean
+cargo build --release
+
+# Run all tests
+cargo test
+```
+
+#### 4. Performance Testing
+
+```bash
+# Bundle size check
+du -sh target/release/smokesignal
+
+# Translation lookup benchmarks
+cargo bench i18n_benchmarks
+```
+
+### Production Configuration
+
+#### Environment Variables
+
+```bash
+# Set appropriate log level
+export RUST_LOG=warn,smokesignal=info
+
+# Production optimizations
+export CARGO_PROFILE_RELEASE_LTO=true
+export CARGO_PROFILE_RELEASE_STRIP=true
+```
+
+#### Docker Deployment
+
+```dockerfile
+# Dockerfile
+FROM rust:1.83 as builder
+
+WORKDIR /app
+COPY . .
+
+# Build with static i18n resources
+RUN cargo build --release --features embed
+
+FROM debian:bookworm-slim
+COPY --from=builder /app/target/release/smokesignal /usr/local/bin/
+COPY --from=builder /app/templates /app/templates
+COPY --from=builder /app/static /app/static
+
+# Note: i18n files are embedded in binary, no need to copy
+
+CMD ["smokesignal"]
+```
+
+### Monitoring and Observability
+
+#### Add i18n Metrics
+
+```rust
+// Add to your metrics collection
+use metrics::{counter, histogram};
+
+// Track translation lookups
+counter!("i18n.lookups", 1, "locale" => locale.to_string());
+
+// Track template rendering
+histogram!("template.render_duration", duration.as_millis() as f64, 
+          "template" => template_name, "locale" => locale.to_string());
+```
+
+#### Health Checks
+
+```rust
+// Add i18n health check endpoint
+pub async fn handle_health_check() -> Response {
+    // Verify key translations work
+    let test_translation = get_translation(&langid!("en-us"), "ui-welcome", None);
+    
+    if test_translation == "ui-welcome" {
+        // Translation failed
+        (StatusCode::SERVICE_UNAVAILABLE, "i18n system not healthy").into_response()
+    } else {
+        (StatusCode::OK, "healthy").into_response()
+    }
+}
+```
+
+### Maintenance
+
+#### Regular Tasks
+
+1. **Translation Updates**: Review and update translations quarterly
+2. **Key Cleanup**: Remove unused translation keys monthly
+3. **Duplicate Detection**: Run duplicate checker before each release
+4. **Performance Review**: Monitor translation lookup performance
+
+#### Backup and Recovery
+
+```bash
+# Backup translation files
+tar -czf i18n-backup-$(date +%Y%m%d).tar.gz i18n/
+
+# Version control all translation changes
+git add i18n/
+git commit -m "Update translations for release v1.2.3"
+```
+
+---
+
+## Conclusion
+
+This guide covers the complete lifecycle of i18n development with fluent-templates in smokesignal. The system provides:
+
+- **Developer-Friendly**: Easy template integration with `tr()` functions
+- **Performance-Optimized**: Static loading with zero runtime overhead
+- **Production-Ready**: Comprehensive testing and debugging tools
+- **Scalable**: Easy addition of new languages and locales
+- **HTMX-Compatible**: Seamless integration with dynamic updates
+
+For additional support or questions, refer to:
+
+- [fluent-templates documentation](https://github.com/XAMPPRocky/fluent-templates)
+- [Fluent syntax guide](https://projectfluent.org/fluent/guide/)
+- [MiniJinja template documentation](https://docs.rs/minijinja/latest/minijinja/)
+
+---
+
+**Next Steps**: 
+1. Run `cargo run --bin i18n-tester` to validate your setup
+2. Create your first new locale following the guide above
+3. Develop templates using the best practices outlined
+4. Deploy with confidence using the production checklist
+
+Happy internationalizing! 🌐