smokesignal#

An event and RSVP management system based on ATproto

• Backend: Rust with Axum web framework
• Database: PostgreSQL with SQLx
• Cache: Redis/Valkey for session management
• Templates: Minijinja with fluent-templates for i18n
• Frontend: HTMX + Bulma CSS
• Containerization: Docker with devcontainer supportent application built with Rust, featuring modern internationalization and unified template rendering.

Features#

• Event Management: Create, view, and manage events with full internationalization
• Advanced Filtering: Locale-aware event filtering with translated facets and smart caching
• RSVP System: Allow users to respond to events in their preferred language
• Internationalization:
  • Complete i18n support with fluent-templates (English, French Canadian)
  • Automatic language detection from browser preferences
  • Gender-aware translations for French Canadian
  • Locale-specific date/time formatting and pluralization
• Modern UI: HTMX-powered interactive interface with Bulma CSS
• Template System: Unified template rendering with automatic i18n context enrichment
• Performance:
  • Compile-time translation loading for zero runtime overhead
  • Locale-aware caching with intelligent cache key generation
  • Optimized facet calculation with pre-computed display names
• Authentication: OAuth-based user authentication
• Real-time Updates: Dynamic content updates with HTMX and proper language context

Architecture#

I18n System#

smokesignal features a production-ready internationalization architecture built on fluent-templates:

• Compile-time Loading: Translations are embedded in the binary for zero runtime overhead
• Automatic Language Detection: Smart detection from Accept-Language headers, URL parameters, and user preferences
• Locale-aware Caching: Intelligent cache key generation that includes locale context
• Performance Optimized: Pre-calculated facet display names and cached translation lookups
• Fallback System: Graceful fallback to English when translations are missing
• Gender Support: Complete gender-aware content support for French Canadian
• HTMX Integration: Seamless language context propagation for dynamic content updates

Template Rendering#

The application features a centralized template rendering system that automatically enriches templates with:

• Internationalization: Automatic locale detection and translation injection
• HTMX Context: Smart detection of HTMX requests for partial rendering
• Gender Context: Personalized content based on user gender preferences
• Error Handling: Consistent error templates with proper context

Technology Stack#

• Backend: Rust with Axum web framework
• Database: PostgreSQL with SQLx
• Cache: Redis/Valkey for session management
• Templates: Minijinja with fluent-templates for i18n
• Frontend: HTMX + Bulma CSS
• Containerization: Docker with devcontainer support

Quick Start#

Using Devcontainers (Recommended)#

1. Install Visual Studio Code and the Dev Containers extension
2. Clone this repository
3. Open in VS Code and select "Reopen in Container"
4. Run database migrations: sqlx migrate run
5. Start the server: cargo run --bin smokesignal

Local Development#

Prerequisites:

• Rust 1.86+
• PostgreSQL
• Redis or Valkey

# Install dependencies
cargo build

# Set up database
sqlx migrate run

# Run the application
cargo run --bin smokesignal

# Run tests
cargo test

Configuration#

Copy keys.example.json to keys.json and configure:

• Database connection strings
• OAuth provider credentials
• Redis/Valkey connection
• External service URLs

Internationalization#

Supported Languages#

• en-us: English (United States)
• fr-ca: French (Canada) with gender support

Adding Translations#

1. Add .ftl files to i18n/{locale}/ directories
2. Use Fluent syntax for translations
3. Test with cargo test i18n

Translation Structure#

i18n/
├── en-us/
│   ├── common.ftl     # Common UI strings
│   ├── errors.ftl     # Error messages
│   ├── forms.ftl      # Form labels and validation
│   ├── actions.ftl    # Button and action text
│   └── ui.ftl         # Interface elements
└── fr-ca/
    └── (same structure with French translations)

Development#

Common Commands#

# Build
cargo build

# Run tests
cargo test

# Run specific test suites
cargo test i18n
cargo test template
cargo test middleware_i18n

# Format and lint
cargo fmt
cargo clippy

# Run with debug logging
RUST_LOG=debug cargo run --bin smokesignal

Build Features#

• embed: Embed templates in binary (production)
• reload: Enable template reloading (development)

# Production build with embedded templates
cargo build --release --no-default-features --features embed

# Development build with template reloading
cargo build --no-default-features --features reload

Template Development#

Template Renderer#

The TemplateRenderer provides a unified API for rendering templates with automatic context enrichment:

use smokesignal::http::template_renderer::TemplateRenderer;

// Create renderer with automatic context
let renderer = TemplateRenderer::new(template_engine, i18n_context, language, is_htmx)
    .with_gender_context(gender_context);

// Render template with enriched context
let html = renderer.render("template_name", &context)?;

Template Macros#

Convenient macros for common operations:

// Create renderer quickly
let renderer = create_renderer!(engine, i18n, lang, htmx, gender);

// Render error templates with context preservation
contextual_error!(renderer, "error_template", error_context);

API Documentation#

Core Modules#

• src/http/template_renderer.rs: Unified template rendering system
• src/i18n/: Internationalization with fluent-templates
• src/http/middleware_i18n.rs: Language detection and context injection
• src/http/macros.rs: Convenience macros for handlers

I18n API#

use smokesignal::i18n::{get_translation, I18nTemplateContext};

// Get translation with arguments
let message = get_translation(&locale, "message-key", Some(args));

// Template context for dynamic locale support
let context = I18nTemplateContext::new(loader);

Contributing#

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run cargo test and cargo clippy
5. Submit a pull request

Translation Contributions#

Translation improvements are welcome! Please ensure:

• Complete coverage across all .ftl files
• Gender variants for French Canadian
• Consistent terminology and tone

License MIT#

This project is licensed under the terms specified in the LICENSE file.

Documentation#

Core Documentation#

• Build Instructions
• Local Development Guide
• Release Process

I18n and API Documentation#

• API Documentation: Complete API reference for locale parameters and i18n endpoints
• User Guide: End-user guide for language switching and multilingual features
• Deployment Guide: Production deployment with i18n configuration, caching, and monitoring
• Technical Documentation: Architecture details, template helpers, and code examples
• I18n API Reference: Template rendering system and i18n integration details

Legacy Documentation#

• Template Rendering System Documentation