# ADR-018: Help System Fluent Integration & Data-Driven Architecture\n\n**Status**: Proposed\n**Date**: 2026-01-13\n**Author**: Architecture Team\n**Supersedes**: Hardcoded help strings in `main_provisioning/help_system.nu`\n\n## Context\n\nThe current help system in `main_provisioning/help_system.nu` (1303 lines) consists almost entirely of hardcoded string concatenation with embedded\nANSI formatting codes:\n\n```\ndef help-infrastructure [] {\n    print "╔════════════════════════════════════════════════════╗"\n    print "║   SERVER & INFRASTRUCTURE                          ║"\n    print "╚════════════════════════════════════════════════════╝"\n}\n```\n\n**Current Problems**:\n\n1. **No Internationalization**: Help text trapped in English-only code\n2. **Hard to Maintain**: Updating text requires editing Nushell code\n3. **Mixed Concerns**: Content (strings) mixed with presentation (ANSI codes)\n4. **No Hot-Reload**: Changes require recompilation\n5. **Difficult to Test**: String content buried in function definitions\n\n## Problem Statement\n\n**Metrics**:\n- 1303 lines of code-embedded help text\n- 17 help categories with 65 strings total\n- All help functions manually maintained\n- No separation of data from presentation\n\n## Decision\n\nImplement **Data-Driven Help with Mozilla Fluent Integration**:\n\n1. Extract help content to Fluent files (`.ftl` format)\n2. Support multilingual help (English base, Spanish translations)\n3. Implement runtime language resolution via `LANG` environment variable\n4. Reduce help_system.nu to wrapper functions only\n\n### Architecture\n\n```\nHelp Content (Fluent Files)\n  ├─ en-US/help.ftl (65 strings - English base)\n  └─ es-ES/help.ftl (65 strings - Spanish translations)\n\nLanguage Detection & Loading\n  ├─ Check LANG environment variable\n  ├─ Load appropriate Fluent file\n  └─ Implement fallback chain (es-ES → en-US)\n\nHelp System Wrapper\n  ├─ help-main [] - Display main menu\n  ├─ help-infrastructure [] - Infrastructure category\n  ├─ help-orchestration [] - Orchestration category\n  └─ help-setup [] - Setup category\n\nUser Interface\n  ├─ LANG=en_US provisioning help infrastructure\n  └─ LANG=es_ES provisioning help infrastructure\n```\n\n## Implementation\n\n### 1. Fluent File Structure\n\n**en-US/help.ftl**:\n\n```\nhelp-main-title = PROVISIONING SYSTEM\nhelp-main-subtitle = Layered Infrastructure Automation\nhelp-main-categories = COMMAND CATEGORIES\nhelp-main-categories-hint = Use 'provisioning help <category>' for details\nhelp-main-infrastructure-name = infrastructure\nhelp-main-infrastructure-desc = Server, taskserv, cluster, VM, and infra management\nhelp-main-orchestration-name = orchestration\nhelp-main-orchestration-desc = Workflow, batch operations, and orchestrator control\nhelp-infrastructure-title = SERVER & INFRASTRUCTURE\nhelp-infra-server = Server Operations\nhelp-infra-server-create = Create a new server\nhelp-infra-server-list = List all servers\nhelp-infra-server-status = Show server status\nhelp-infra-taskserv = TaskServ Management\nhelp-infra-taskserv-create = Deploy taskserv to server\nhelp-infra-cluster = Cluster Management\nhelp-infra-vm = Virtual Machine Operations\nhelp-orchestration-title = ORCHESTRATION & WORKFLOWS\nhelp-orch-control = Orchestrator Management\nhelp-orch-start = Start orchestrator [--background]\nhelp-orch-workflows = Single Task Workflows\nhelp-orch-batch = Multi-Provider Batch Operations\n```\n\n**es-ES/help.ftl** (Spanish translations):\n\n```\nhelp-main-title = SISTEMA DE PROVISIÓN\nhelp-main-subtitle = Automatización de Infraestructura por Capas\nhelp-main-categories = CATEGORÍAS DE COMANDOS\nhelp-main-categories-hint = Use 'provisioning help <categoría>' para más detalles\nhelp-main-infrastructure-name = infraestructura\nhelp-main-infrastructure-desc = Gestión de servidores, taskserv, clusters, VM e infraestructura\nhelp-main-orchestration-name = orquestación\nhelp-main-orchestration-desc = Flujos de trabajo, operaciones por lotes y control del orquestador\nhelp-infrastructure-title = SERVIDOR E INFRAESTRUCTURA\nhelp-infra-server = Operaciones de Servidor\nhelp-infra-server-create = Crear un nuevo servidor\nhelp-infra-server-list = Listar todos los servidores\nhelp-infra-server-status = Mostrar estado del servidor\nhelp-infra-taskserv = Gestión de TaskServ\nhelp-infra-taskserv-create = Desplegar taskserv en servidor\nhelp-infra-cluster = Gestión de Clusters\nhelp-infra-vm = Operaciones de Máquinas Virtuales\nhelp-orchestration-title = ORQUESTACIÓN Y FLUJOS DE TRABAJO\nhelp-orch-control = Gestión del Orquestador\nhelp-orch-start = Iniciar orquestador [--background]\nhelp-orch-workflows = Flujos de Trabajo de Tarea Única\nhelp-orch-batch = Operaciones por Lotes Multi-Proveedor\n```\n\n### 2. Fluent Loading in Nushell\n\n```\ndef load-fluent-file [category: string] {\n    let lang = ($env.LANG? | default "en_US" | str replace "_" "-")\n    let fluent_path = $"provisioning/locales/($lang)/help.ftl"\n\n    # Parse Fluent file and extract strings for category\n    # Fallback to en-US if lang not available\n}\n```\n\n### 3. Help System Wrapper\n\n```\nexport def help-infrastructure [] {\n    let strings = (load-fluent-file "infrastructure")\n\n    # Apply formatting and render\n    print $"╔════════════════════════════════════════════════════╗"\n    print $"║   ($strings.title | str upcase)                   ║"\n    print $"╚════════════════════════════════════════════════════╝"\n}\n```\n\n## Consequences\n\n### Positive\n\n- **Internationalization Ready**: Easy to add new languages (Portuguese, French, Japanese)\n- **Data/Presentation Separation**: Content in Fluent, formatting in Nushell\n- **Maintainability**: Edit Fluent files, not Nushell code\n- **Hot-Reload Support**: Can update help text without recompilation\n- **Testing**: Help content testable independently from rendering\n- **Code Reduction**: 1303 lines → ~50 lines (wrapper) + ~700 lines (Fluent data)\n\n### Negative\n\n- **Tool Complexity**: Need Fluent parser and loader\n- **Fallback Chain Management**: Must handle missing translations gracefully\n- **Performance**: File I/O for loading translations (mitigated by caching)\n\n## Integration Strategy\n\n### Phase 1: Infrastructure & Extraction\n\n- ✅ Create `provisioning/locales/` directory structure\n- ✅ Create `i18n-config.toml` with locale configuration\n- ✅ Extract strings to `en-US/help.ftl` (65 strings)\n- ✅ Create Spanish translations `es-ES/help.ftl`\n\n### Phase 2: Integration (This Task)\n\n- [ ] Modify `help_system.nu` to load from Fluent\n- [ ] Implement language detection (`$env.LANG`)\n- [ ] Implement fallback chain logic\n- [ ] Test with `LANG=en_US` and `LANG=es_ES`\n\n### Phase 3: Validation & Documentation\n\n- [ ] Comprehensive integration tests\n- [ ] Performance benchmarks\n- [ ] Documentation for adding new languages\n- [ ] Examples in provisioning/docs/\n\n## Language Resolution Flow\n\n```\n1. Check LANG environment variable\n   LANG=es_ES.UTF-8 → extract "es_ES" or "es-ES"\n\n2. Check if locale file exists\n   provisioning/locales/es-ES/help.ftl exists? → YES\n\n3. Load locale file\n   Parse and extract help strings\n\n4. On missing key:\n   Check fallback chain in i18n-config.toml\n   es-ES → en-US\n\n5. Render with formatting\n   Apply ANSI codes, boxes, alignment\n```\n\n## Testing Strategy\n\n### Unit Tests\n\n```\n# Test language detection\nLANG=en_US provisioning help infrastructure\n# Expected: English output\n\nLANG=es_ES provisioning help infrastructure\n# Expected: Spanish output\n\nLANG=fr_FR provisioning help infrastructure\n# Expected: Fallback to English (fr-FR not available)\n```\n\n## File Structure\n\n```\nprovisioning/\n├── locales/\n│   ├── i18n-config.toml           # Locale metadata & fallback chains\n│   ├── en-US/\n│   │   └── help.ftl               # 65 English help strings\n│   └── es-ES/\n│       └── help.ftl               # 65 Spanish help strings\n└── core/nulib/main_provisioning/\n    └── help_system.nu             # ~50 lines (wrapper only)\n```\n\n## Configuration\n\n**i18n-config.toml** defines:\n\n```\n[locales]\ndefault = "en-US"\nfallback = "en-US"\n\n[locales.en-US]\nname = "English (United States)"\n\n[locales.es-ES]\nname = "Spanish (Spain)"\n\n[fallback_chains]\nes-ES = ["en-US"]\n```\n\n## Related ADRs\n\n- **ADR-010**: Configuration Format Strategy\n- **ADR-011**: Nickel Migration\n- **ADR-013**: TypeDialog Integration (forms also use Fluent)\n\n## Open Questions\n\n1. Should help strings support Fluent attributes for metadata?\n2. Should we implement Fluent caching for performance?\n3. How do we handle dynamic help (commands not in Fluent)?\n4. Should help system auto-update when Fluent files change?\n\n## References\n\n- Mozilla Fluent: [https://projectfluent.org/](https://projectfluent.org/)\n- Fluent Syntax: [https://projectfluent.org/fluent/guide/](https://projectfluent.org/fluent/guide/)\n- Nushell 0.109 Guidelines: `.claude/guidelines/nushell.md`\n- Current Help Implementation: `provisioning/core/nulib/main_provisioning/help_system.nu`\n- Fluent Files: `provisioning/locales/{en-US,es-ES}/help.ftl`\n
