1 line
No EOL
11 KiB
Markdown
1 line
No EOL
11 KiB
Markdown
# 🌐 AuroraFrame Hierarchical i18n Architecture\n\n## **Complete Implementation Overview**\n\nThis document describes AuroraFrame's advanced internationalization system that supports **global + page-specific locales** with **AI-powered translation assistance**, **type-safe configuration**, and **build-time optimization**.\n\n---\n\n## **🏗️ Architecture Components**\n\n### **1. Configuration Layer (KCL Schemas)**\n\n**Type-safe i18n configuration with compile-time validation:**\n\n```plaintext\nframework/schemas/i18n-config.k # KCL schemas for i18n configuration\nconfig/site.k # Site-wide i18n configuration\npages/{page}/config.k # Page-specific i18n overrides\n```\n\n### **2. Directory Structure**\n\n**Hierarchical locale organization:**\n\n```plaintext\nlocales/\n├── global/ # Site-wide translations\n│ ├── en-US/\n│ │ ├── common.ftl # Navigation, UI, errors\n│ │ ├── forms.ftl # Form elements\n│ │ └── emails.ftl # Email templates\n│ ├── es-ES/\n│ │ ├── common.ftl\n│ │ └── ...\n│ └── fr-FR/\n│ └── ...\n├── pages/ # Page-specific translations\n│ ├── blog/\n│ │ ├── en-US/\n│ │ │ ├── blog.ftl # Blog-specific messages\n│ │ │ └── categories.ftl # Blog categories\n│ │ └── es-ES/\n│ │ └── blog.ftl\n│ ├── products/\n│ │ └── ...\n│ └── about/\n│ └── ...\n```\n\n### **3. Processing Layer**\n\n#### **A. Rust Plugin (`nu_plugin_fluent`)**\n\n**High-performance FTL processing:**\n\n```rust\n// Core commands\nfluent parse <file> // Parse FTL files\nfluent localize <msg> <locale> // Get localized message\nfluent create-bundle <locale> // Merge global + page locales\nfluent validate <file> // Validate FTL syntax\nfluent extract <file> // Extract message IDs\nfluent list-locales <dir> // List available locales\n```\n\n#### **B. Nushell Framework (`framework/i18n.nu`)**\n\n**Intelligent locale resolution and caching:**\n\n```nu\n# Core functions\nresolve_locale_chain # Priority: page > global > fallback\nload_merged_locales # Merge global + page-specific\ndetect_locale # Smart locale detection\nget_message # Get localized message with fallbacks\nvalidate_i18n_build # Build-time validation\nbuild_locale_bundles # Generate optimized bundles\n```\n\n#### **C. AI Integration (`framework/ai-i18n.nu`)**\n\n**AI-powered translation assistance:**\n\n```nu\n# AI commands\naurora ai i18n translate <from> <to> # Generate translations\naurora ai i18n validate # Validate translations\naurora ai i18n extract <templates> # Extract strings from templates\naurora ai i18n optimize # Suggest improvements\naurora ai i18n init # Initialize with AI assistance\n```\n\n---\n\n## **🔄 Locale Resolution Flow**\n\n### **Priority Chain**\n\n1. **Page-specific locale files** (highest priority)\n2. **Global locale files**\n3. **Fallback locales** (from page config)\n4. **Global fallback chain** (lowest priority)\n\n### **Example Resolution**\n\nFor a **blog page** in **Spanish (es-ES)**:\n\n```plaintext\n1. locales/pages/blog/es-ES/blog.ftl # Blog-specific Spanish\n2. locales/global/es-ES/common.ftl # Global Spanish\n3. locales/global/en-US/common.ftl # Fallback to English\n4. [[message-id]] # Ultimate fallback\n```\n\n### **Merge Strategies**\n\n```kcl\n# Page configuration\ni18n = {\n extends_global = True # Inherit global messages\n override_global = True # Can override global messages\n locale_files = ["blog.ftl"] # Additional page-specific files\n}\n```\n\n---\n\n## **⚡ Build-Time Optimization**\n\n### **Bundle Strategies**\n\n#### **1. Global Bundle** (Single file per locale)\n\n```plaintext\ndist/locales/en-US.json # All messages for en-US\ndist/locales/es-ES.json # All messages for es-ES\n```\n\n#### **2. Per-Page Bundles** (Separate file for each page)\n\n```plaintext\ndist/locales/en-US-global.json # Global messages\ndist/locales/en-US-blog.json # Blog-specific messages\ndist/locales/en-US-products.json # Product-specific messages\n```\n\n#### **3. Hybrid Strategy** (Optimal performance)\n\n```plaintext\ndist/locales/en-US-global.json # Shared across all pages\ndist/locales/en-US-blog.json # Blog additions only\ndist/locales/en-US-products.json # Product additions only\n```\n\n### **Build Process**\n\n```nu\n# Validation\naurora validate i18n # Check all configurations\naurora validate locales # Validate FTL files\n\n# Building\naurora build --locales # Generate optimized bundles\naurora build --i18n-stats # Show translation statistics\n```\n\n---\n\n## **🤖 AI-Powered Features**\n\n### **Translation Generation**\n\n**From English to Spanish:**\n\n```bash\naurora ai i18n translate en-US es-ES --page blog --context "Tech blog about web development"\n```\n\n**Generated FTL:**\n\n```ftl\n# Blog-specific translations (Spanish)\nblog-title = Blog de AuroraFrame\npost-read-time =\n { $minutes ->\n [one] 1 min de lectura\n *[other] { $minutes } min de lectura\n }\n```\n\n### **String Extraction**\n\n**Extract from templates:**\n\n```bash\naurora ai i18n extract ["src/**/*.html"] --page blog\n```\n\n**AI identifies:**\n\n- User-facing text\n- Suggests message IDs\n- Provides context for translators\n- Avoids duplicating existing messages\n\n### **Translation Validation**\n\n**Multi-locale validation:**\n\n```bash\naurora ai i18n validate --locales [en-US, es-ES, fr-FR]\n```\n\n**AI checks for:**\n\n- Completeness (missing translations)\n- Consistency (terminology alignment)\n- Cultural appropriateness\n- Technical accuracy (placeholders, plurals)\n\n---\n\n## **🔧 Developer Experience**\n\n### **Template Integration**\n\n**Tera Filter Usage:**\n\n```html\n<!-- Global message -->\n<h1>{{ "welcome-title" | t }}</h1>\n\n<!-- With arguments -->\n<p>{{ "user-greeting" | t(name=user.name) }}</p>\n\n<!-- Page-specific message (auto-resolved) -->\n<h2>{{ "blog-title" | t }}</h2>\n```\n\n### **Smart Locale Detection**\n\n**Priority order:**\n\n1. URL parameter: `/es/blog`\n2. Cookie: `locale=es-ES`\n3. Accept-Language header\n4. System locale\n5. Site default\n\n### **Hot Reload Support**\n\n**Development mode:**\n\n```bash\naurora dev --i18n-watch # Watch FTL files for changes\n```\n\n**Automatically:**\n\n- Reloads changed FTL files\n- Validates syntax\n- Updates browser\n- Shows missing translations\n\n---\n\n## **📊 Performance Optimizations**\n\n### **Caching Strategy**\n\n```nu\n# Memory cache for parsed bundles\nmut $locale_bundles = {}\n\n# Cache key: "locale:page"\n# Cache hit avoids re-parsing FTL files\n```\n\n### **Bundle Splitting**\n\n**Hybrid strategy benefits:**\n\n- **Global bundle**: Shared across pages (cached)\n- **Page bundles**: Only additional messages\n- **Lazy loading**: Load page bundles on demand\n- **Minimal overhead**: No duplicate messages\n\n### **Build Metrics**\n\n```plaintext\n📊 i18n Build Stats:\n Global messages: 145 (en-US), 142 (es-ES), 138 (fr-FR)\n Blog messages: 23 (en-US), 23 (es-ES), 21 (fr-FR)\n Bundle sizes: 12KB (global), 3KB (blog)\n Missing translations: 7 (fr-FR)\n```\n\n---\n\n## **🔒 Type Safety & Validation**\n\n### **Compile-Time Checks**\n\n**KCL validation ensures:**\n\n```kcl\ncheck SiteI18nValidation:\n # Default locale must exist\n site.i18n.default_locale in available_locale_codes\n\n # Fallback locales must be valid\n all fallback in site.i18n.fallback_chain {\n fallback in available_locale_codes\n }\n```\n\n### **Message ID Validation**\n\n**At build time:**\n\n- All referenced message IDs exist\n- No orphaned translations\n- Placeholder consistency across locales\n- Plural rule validation\n\n---\n\n## **🚀 Usage Examples**\n\n### **1. Add New Locale**\n\n```bash\n# 1. Update site configuration\n# Add locale to site.k\n\n# 2. Generate translations with AI\naurora ai i18n translate en-US ja-JP --interactive\n\n# 3. Validate results\naurora ai i18n validate --locales [en-US, ja-JP]\n\n# 4. Build optimized bundles\naurora build --locales\n```\n\n### **2. Create Page-Specific Translations**\n\n```bash\n# 1. Configure page i18n\n# Edit pages/products/config.k\n\n# 2. Create locale files\nmkdir locales/pages/products/{en-US,es-ES}\n\n# 3. Extract strings from templates\naurora ai i18n extract ["pages/products/src/**/*.html"] --page products\n\n# 4. Generate translations\naurora ai i18n translate en-US es-ES --page products --namespace products\n```\n\n### **3. Optimize Existing Translations**\n\n```bash\n# Analyze current structure\naurora ai i18n optimize --analyze-usage --performance\n\n# Get improvement suggestions\n# - Bundle size optimizations\n# - Missing translation opportunities\n# - Performance improvements\n# - Maintenance suggestions\n```\n\n---\n\n## **🌟 Benefits Summary**\n\n### **For Developers**\n\n- ✅ **Type-safe** i18n configuration with KCL\n- ✅ **Hierarchical** locale system (global + page-specific)\n- ✅ **AI-powered** translation generation\n- ✅ **Hot reload** support for development\n- ✅ **Native Nushell** integration\n\n### **For Content Teams**\n\n- ✅ **Context-aware** AI translations\n- ✅ **Cultural appropriateness** validation\n- ✅ **Automatic string extraction** from templates\n- ✅ **Translation completeness** tracking\n\n### **For Performance**\n\n- ✅ **Rust-powered** FTL processing\n- ✅ **Smart caching** system\n- ✅ **Optimized bundle** splitting\n- ✅ **Lazy loading** support\n\n### **For Maintainability**\n\n- ✅ **Compile-time validation** prevents runtime errors\n- ✅ **AI suggestions** for improvements\n- ✅ **Consistent terminology** across locales\n- ✅ **Easy scaling** to new locales/pages\n\n---\n\n## **🔮 Future Enhancements**\n\n### **Planned Features**\n\n- **Visual i18n editor** with live preview\n- **Translation memory** integration\n- **Pluralization rule** auto-generation\n- **RTL language** full support\n- **Translation workflows** with approval chains\n- **Performance monitoring** and optimization\n\n### **AI Capabilities**\n\n- **Context-aware** translations using page content\n- **Brand voice** consistency across locales\n- **Cultural adaptation** suggestions\n- **Translation quality** scoring\n- **Automated QA** testing for i18n\n\n---\n\n**AuroraFrame's i18n system represents the future of intelligent, type-safe, and performant internationalization for web applications.** 🌅\n\n*Build at the speed of thought. Localize at the speed of light.* ⚡ |