11 KiB
11 KiB
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\nHierarchical locale organization:\n\nplaintext\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\nHigh-performance FTL processing:\n\nrust\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\nIntelligent locale resolution and caching:\n\nnu\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\nAI-powered translation assistance:\n\nnu\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\nplaintext\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\nkcl\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\nplaintext\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\nplaintext\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\nplaintext\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\nnu\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\nFrom English to Spanish:\n\nbash\naurora ai i18n translate en-US es-ES --page blog --context "Tech blog about web development"\n\n\nGenerated FTL:\n\nftl\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\nExtract from templates:\n\nbash\naurora ai i18n extract ["src/**/*.html"] --page blog\n\n\nAI 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\nMulti-locale validation:\n\nbash\naurora ai i18n validate --locales [en-US, es-ES, fr-FR]\n\n\nAI 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\nTera Filter Usage:\n\nhtml\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\nPriority 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\nDevelopment mode:\n\nbash\naurora dev --i18n-watch # Watch FTL files for changes\n\n\nAutomatically:\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\nnu\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\nHybrid 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\nplaintext\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\nKCL validation ensures:\n\nkcl\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\nAt 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\nbash\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\nbash\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\nbash\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\nAuroraFrame's i18n system represents the future of intelligent, type-safe, and performant internationalization for web applications. 🌅\n\nBuild at the speed of thought. Localize at the speed of light. ⚡