1 line
11 KiB
Markdown
1 line
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-Tim
|