kayrozen.com
forked from
smokesignal.events/smokesignal
i18n+filtering fork - fluent-templates v2
1# smokesignal
2
3An event and RSVP management system based on ATproto
4- **Backend**: Rust with Axum web framework
5- **Database**: PostgreSQL with SQLx
6- **Cache**: Redis/Valkey for session management
7- **Templates**: Minijinja with fluent-templates for i18n
8- **Frontend**: HTMX + Bulma CSS
9- **Containerization**: Docker with devcontainer supportent application built with Rust, featuring modern internationalization and unified template rendering.
10
11## Features
12
13- **Event Management**: Create, view, and manage events with full internationalization
14- **Advanced Filtering**: Locale-aware event filtering with translated facets and smart caching
15- **RSVP System**: Allow users to respond to events in their preferred language
16- **Internationalization**:
17 - Complete i18n support with fluent-templates (English, French Canadian)
18 - Automatic language detection from browser preferences
19 - Gender-aware translations for French Canadian
20 - Locale-specific date/time formatting and pluralization
21- **Modern UI**: HTMX-powered interactive interface with Bulma CSS
22- **Template System**: Unified template rendering with automatic i18n context enrichment
23- **Performance**:
24 - Compile-time translation loading for zero runtime overhead
25 - Locale-aware caching with intelligent cache key generation
26 - Optimized facet calculation with pre-computed display names
27- **Authentication**: OAuth-based user authentication
28- **Real-time Updates**: Dynamic content updates with HTMX and proper language context
29
30## Architecture
31
32### I18n System
33smokesignal features a production-ready internationalization architecture built on `fluent-templates`:
34
35- **Compile-time Loading**: Translations are embedded in the binary for zero runtime overhead
36- **Automatic Language Detection**: Smart detection from Accept-Language headers, URL parameters, and user preferences
37- **Locale-aware Caching**: Intelligent cache key generation that includes locale context
38- **Performance Optimized**: Pre-calculated facet display names and cached translation lookups
39- **Fallback System**: Graceful fallback to English when translations are missing
40- **Gender Support**: Complete gender-aware content support for French Canadian
41- **HTMX Integration**: Seamless language context propagation for dynamic content updates
42
43### Template Rendering
44The application features a centralized template rendering system that automatically enriches templates with:
45
46- **Internationalization**: Automatic locale detection and translation injection
47- **HTMX Context**: Smart detection of HTMX requests for partial rendering
48- **Gender Context**: Personalized content based on user gender preferences
49- **Error Handling**: Consistent error templates with proper context
50
51### Technology Stack
52
53- **Backend**: Rust with Axum web framework
54- **Database**: PostgreSQL with SQLx
55- **Cache**: Redis/Valkey for session management
56- **Templates**: Minijinja with fluent-templates for i18n
57- **Frontend**: HTMX + Bulma CSS
58- **Containerization**: Docker with devcontainer support
59
60## Quick Start
61
62### Using Devcontainers (Recommended)
63
641. Install [Visual Studio Code](https://code.visualstudio.com/) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
652. Clone this repository
663. Open in VS Code and select "Reopen in Container"
674. Run database migrations: `sqlx migrate run`
685. Start the server: `cargo run --bin smokesignal`
69
70### Local Development
71
72Prerequisites:
73- Rust 1.86+
74- PostgreSQL
75- Redis or Valkey
76
77```bash
78# Install dependencies
79cargo build
80
81# Set up database
82sqlx migrate run
83
84# Run the application
85cargo run --bin smokesignal
86
87# Run tests
88cargo test
89```
90
91## Configuration
92
93Copy `keys.example.json` to `keys.json` and configure:
94
95- Database connection strings
96- OAuth provider credentials
97- Redis/Valkey connection
98- External service URLs
99
100## Internationalization
101
102### Supported Languages
103- **en-us**: English (United States)
104- **fr-ca**: French (Canada) with gender support
105
106### Adding Translations
1071. Add `.ftl` files to `i18n/{locale}/` directories
1082. Use Fluent syntax for translations
1093. Test with `cargo test i18n`
110
111### Translation Structure
112```
113i18n/
114├── en-us/
115│ ├── common.ftl # Common UI strings
116│ ├── errors.ftl # Error messages
117│ ├── forms.ftl # Form labels and validation
118│ ├── actions.ftl # Button and action text
119│ └── ui.ftl # Interface elements
120└── fr-ca/
121 └── (same structure with French translations)
122```
123
124## Development
125
126### Common Commands
127```bash
128# Build
129cargo build
130
131# Run tests
132cargo test
133
134# Run specific test suites
135cargo test i18n
136cargo test template
137cargo test middleware_i18n
138
139# Format and lint
140cargo fmt
141cargo clippy
142
143# Run with debug logging
144RUST_LOG=debug cargo run --bin smokesignal
145```
146
147### Build Features
148- `embed`: Embed templates in binary (production)
149- `reload`: Enable template reloading (development)
150
151```bash
152# Production build with embedded templates
153cargo build --release --no-default-features --features embed
154
155# Development build with template reloading
156cargo build --no-default-features --features reload
157```
158
159## Template Development
160
161### Template Renderer
162The `TemplateRenderer` provides a unified API for rendering templates with automatic context enrichment:
163
164```rust
165use smokesignal::http::template_renderer::TemplateRenderer;
166
167// Create renderer with automatic context
168let renderer = TemplateRenderer::new(template_engine, i18n_context, language, is_htmx)
169 .with_gender_context(gender_context);
170
171// Render template with enriched context
172let html = renderer.render("template_name", &context)?;
173```
174
175### Template Macros
176Convenient macros for common operations:
177
178```rust
179// Create renderer quickly
180let renderer = create_renderer!(engine, i18n, lang, htmx, gender);
181
182// Render error templates with context preservation
183contextual_error!(renderer, "error_template", error_context);
184```
185
186## API Documentation
187
188### Core Modules
189
190- `src/http/template_renderer.rs`: Unified template rendering system
191- `src/i18n/`: Internationalization with fluent-templates
192- `src/http/middleware_i18n.rs`: Language detection and context injection
193- `src/http/macros.rs`: Convenience macros for handlers
194
195### I18n API
196
197```rust
198use smokesignal::i18n::{get_translation, I18nTemplateContext};
199
200// Get translation with arguments
201let message = get_translation(&locale, "message-key", Some(args));
202
203// Template context for dynamic locale support
204let context = I18nTemplateContext::new(loader);
205```
206
207## Contributing
208
2091. Fork the repository
2102. Create a feature branch
2113. Make changes with tests
2124. Run `cargo test` and `cargo clippy`
2135. Submit a pull request
214
215### Translation Contributions
216Translation improvements are welcome! Please ensure:
217- Complete coverage across all `.ftl` files
218- Gender variants for French Canadian
219- Consistent terminology and tone
220
221## License MIT
222
223This project is licensed under the terms specified in the LICENSE file.
224
225## Documentation
226
227### Core Documentation
228- [Build Instructions](BUILD.md)
229- [Local Development Guide](playbooks/localdev.md)
230- [Release Process](playbooks/release.md)
231
232### I18n and API Documentation
233- **[API Documentation](docs/api/LOCALE_PARAMETERS.md)**: Complete API reference for locale parameters and i18n endpoints
234- **[User Guide](docs/USER_GUIDE.md)**: End-user guide for language switching and multilingual features
235- **[Deployment Guide](docs/DEPLOYMENT_I18N.md)**: Production deployment with i18n configuration, caching, and monitoring
236- **[Technical Documentation](docs/TECHNICAL_I18N.md)**: Architecture details, template helpers, and code examples
237- **[I18n API Reference](docs/i18n/API_REFERENCE.md)**: Template rendering system and i18n integration details
238
239### Legacy Documentation
240- [Template Rendering System Documentation](docs/FINAL_STATUS.md)