# Internationalization System Guide\n\n## Overview\n\nThe provisioning system supports multilingual help and user interfaces through **Mozilla Fluent** (`.ftl` format), a modern i18n framework designed\nfor localization at scale.\n\n**Current Status:**\n- ✅ English (en-US) - Base language\n- ✅ Spanish (es-ES) - Active translation\n- 🔄 Extensible framework - Easy to add more languages\n\n## Architecture\n\n### Directory Structure\n\n```\nprovisioning/locales/\n├── i18n-config.toml           # Locale metadata and fallback chains\n├── en-US/\n│   ├── help.ftl               # Help system strings (65 strings)\n│   └── forms.ftl              # Form labels and messages (180 strings)\n└── es-ES/\n    ├── help.ftl               # Spanish help translations\n    └── forms.ftl              # Spanish form translations\n```\n\n### File Organization\n\n- **`help.ftl`**: Help system messages (category names, descriptions, tips)\n- **`forms.ftl`**: User interface forms (labels, placeholders, validation messages)\n- **`i18n-config.toml`**: Configuration for locale metadata and fallback chains\n\n### Fluent Format Reference\n\nFluent files use a simple key-value format:\n\n```\n# Comments start with #\nkey = value\ncategory-name = Category Name\nhelp-infrastructure-desc = Server, taskserv, cluster, and VM management\n```\n\n**Key Rules:**\n1. One entry per line\n2. Keys use lowercase with hyphens (not underscores)\n3. Values can contain any text (no escaping needed)\n4. Comments are ignored by the loader\n\n## Language Selection\n\n### Automatic Detection\n\nThe system automatically detects the active language via the `LANG` environment variable:\n\n```\n# English (default)\nLANG=en_US provisioning help\n\n# Spanish\nLANG=es_ES provisioning help\n\n# With encoding suffix (automatically stripped)\nLANG=es_ES.UTF-8 provisioning help\n```\n\n### Locale Format\n\nThe system parses standard POSIX locale format:\n- `en_US` → detects English\n- `es_ES` → detects Spanish\n- `fr_FR.UTF-8` → strips `.UTF-8` suffix → detects French (if available)\n- `xx_XX` → falls back to English\n\n## Help System Integration\n\n### Runtime Language Loading\n\nThe help system (`help_system_fluent.nu`) uses three key functions:\n\n#### 1. Locale Detection\n\n```\ndef get-active-locale [] {\n    # Parses LANG env var and returns locale code\n    # Example: "es_ES.UTF-8" → "es-ES"\n}\n```\n\n#### 2. Fluent Parsing\n\n```\ndef parse-fluent [content: string] {\n    # Parses .ftl file format into record of key-value pairs\n    # Skips comments and empty lines\n}\n```\n\n#### 3. String Lookup with Fallback\n\n```\ndef get-help-string [key: string] {\n    # Looks up key in active locale\n    # Falls back to en-US if not found\n    # Returns [key] if completely missing\n}\n```\n\n### Usage in Help Functions\n\nHelp functions precompute all strings, then use them in print statements:\n\n```\ndef help-infrastructure [] {\n    let title = (get-help-string "help-infrastructure-title")\n    let server = (get-help-string "help-infra-server")\n    let vm = (get-help-string "help-infra-vm")\n\n    print $"╔════════════════════════════════════════════╗"\n    print $"║ ($title) ║"\n    print $"╚════════════════════════════════════════════╝"\n    print ""\n    print $"🖥️  ($server)"\n    print $"💾 ($vm)"\n}\n```\n\n**Key Practice:** Always pre-compute translated strings before using them in interpolation for reliability in Nushell 0.109.\n\n## Forms Integration\n\nTypeDialog forms automatically load translations when configured:\n\n```\n# In form definition\n"locales_path": "provisioning/locales"\n```\n\nForm labels and validation messages use the same Fluent files:\n\n```\nform-label-password = Contraseña\nform-error-password-required = La contraseña es obligatoria\nform-placeholder-email = correo@ejemplo.com\n```\n\n## Adding a New Language\n\n### Step 1: Create Locale Directory\n\n```\nmkdir -p provisioning/locales/fr-FR\ntouch provisioning/locales/fr-FR/help.ftl\ntouch provisioning/locales/fr-FR/forms.ftl\n```\n\n### Step 2: Copy English Template\n\nUse English files as template:\n\n```\ncp provisioning/locales/en-US/help.ftl provisioning/locales/fr-FR/help.ftl\n```\n\n### Step 3: Translate Content\n\nEdit the new files and translate all values:\n\n```\n# Before (English template)\nhelp-main-title = PROVISIONING SYSTEM\nhelp-main-subtitle = Layered Infrastructure Automation\n\n# After (French translation)\nhelp-main-title = SYSTÈME DE PROVISIONING\nhelp-main-subtitle = Automation Infrastructurelle Stratifiée\n```\n\n**Important:** Keep all keys identical - only translate the values.\n\n### Step 4: Update Configuration\n\nAdd the new locale to `provisioning/locales/i18n-config.toml`:\n\n```\n[locales.fr-FR]\nname = "French (France)"\n\n[fallback_chains]\nfr-FR = ["en-US"]\n```\n\n### Step 5: Test\n\n```\n# Test with the new locale\nLANG=fr_FR provisioning help\n\n# Test fallback (English appears if translation missing)\nLANG=fr_FR provisioning help infrastructure\n```\n\n## Fallback Chain Strategy\n\nWhen a translation is missing, the system follows this chain:\n\n```\nActive Locale (es-ES)\n    ↓\nFallback Locale (defined in i18n-config.toml)\n    ↓\nEnglish (en-US) - Final fallback\n```\n\nExample configuration:\n\n```\n[fallback_chains]\nes-ES = ["en-US"]     # Spanish falls back to English\npt-BR = ["pt-PT", "en-US"]  # Brazilian Portuguese → Portuguese → English\n```\n\n## Translation Guidelines\n\n### Command Names\n\n**MUST NOT be translated** - keep in English:\n```\n# WRONG ❌\nhelp-main-infrastructure-name = infraestructura\n\n# CORRECT ✅\nhelp-main-infrastructure-name = infrastructure\n```\n\nReason: Command aliases must remain consistent across all languages for CLI compatibility.\n\n### Descriptions\n\n**SHOULD be translated** - translate descriptions fully:\n```\nhelp-main-infrastructure-desc = Server, taskserv, cluster, VM, and infra management\n# Spanish:\nhelp-main-infrastructure-desc = Gestión de servidores, taskserv, clusters, VM e infraestructura\n```\n\n### Error Messages\n\n**SHOULD be translated** - translate fully for user experience:\n```\nhelp-error-unknown-category = Unknown help category\n# Spanish:\nhelp-error-unknown-category = Categoría de ayuda desconocida\n```\n\n### Options and Flags\n\n**MUST NOT be translated** - keep in English:\n```\nhelp-orch-start = Start orchestrator [--background]\n# Spanish:\nhelp-orch-start = Iniciar orquestador [--background]  # Keep [--background] as-is\n```\n\n## Accessing Translations Programmatically\n\n### From Nushell Code\n\n```\nuse provisioning/core/nulib/main_provisioning/help_system_fluent.nu *\n\n# Get a translated string\nlet title = (get-help-string "help-main-title")\nprint $title  # Output depends on LANG env var\n```\n\n### From Forms\n\nForms automatically use the configured locale path:\n\n```\n# Form config\n"locales_path": "provisioning/locales"\n\n# Labels are automatically translated\n"fields": [\n    {\n        "name": "password",\n        "label_key": "form-label-password",  # Looked up from locale\n        "type": "password"\n    }\n]\n```\n\n## Testing Multilingual Functionality\n\n### Manual Testing\n\n```\n# Test English\nLANG=en_US nu -c 'use provisioning/core/nulib/main_provisioning/help_system_fluent.nu *; provisioning-help'\n\n# Test Spanish\nLANG=es_ES nu -c 'use provisioning/core/nulib/main_provisioning/help_system_fluent.nu *; provisioning-help'\n\n# Test infrastructure help in both languages\nLANG=en_US provisioning-help infrastructure\nLANG=es_ES provisioning-help infrastructure\n\n# Test fallback (non-existent locale defaults to English)\nLANG=fr_FR provisioning-help\n```\n\n### Automated Testing\n\nRun the comprehensive test suite:\n\n```\nnu -c 'source tests/test-multilingual-help.nu; test-all'\n```\n\nTest results show:\n- ✅ English main help\n- ✅ Spanish main help\n- ✅ English category helps\n- ✅ Spanish category helps\n- ✅ Fallback to English for missing locales\n\n## Performance Considerations\n\n### Caching\n\nFluent files are loaded on-demand and parsed each time:\n- Help requests: < 100ms per locale\n- No persistent caching currently implemented\n- Suitable for interactive use\n\n### Optimization Opportunities\n\nFor future improvements:\n1. **File Caching**: Cache parsed Fluent in memory\n2. **Lazy Loading**: Only load used keys (not entire files)\n3. **Binary Format**: Convert `.ftl` to faster binary format\n\n## Troubleshooting\n\n### Translation Not Appearing\n\n**Problem**: Help shows English instead of Spanish\n```\n# Check\nLANG=es_ES provisioning-help\n# Output: English text\n```\n\n**Solutions:**\n1. Verify `LANG` is set correctly: `echo $env.LANG`\n2. Check file exists: `ls provisioning/locales/es-ES/help.ftl`\n3. Verify syntax: Check that `.ftl` files have valid `key = value` format\n4. Run tests: `nu -c 'source tests/test-multilingual-help.nu; test-all'`\n\n### Missing Strings Show as [key]\n\n**Problem**: Output shows `[help-main-title]` instead of translated text\n\n**Causes:**\n1. Key typo in code vs. Fluent file\n2. Comment in wrong position in `.ftl` file\n3. Malformed Fluent line (missing `=` sign)\n\n**Solution:**\n1. Verify key exists in Fluent file: `grep "help-main-title" provisioning/locales/en-US/help.ftl`\n2. Check `.ftl` format: Each line should be `key = value`\n3. Look for parse errors in help_system_fluent.nu output\n\n### Encoding Issues\n\n**Problem**: Spanish characters display incorrectly (ñ, á, é, etc.)\n\n**Solution:**\n1. Ensure terminal supports UTF-8: `echo $env.LANG`\n2. Verify `.ftl` files are UTF-8 encoded: `file provisioning/locales/es-ES/help.ftl`\n3. Check Fluent file content: `head provisioning/locales/es-ES/help.ftl`\n\n## Related Documents\n\n- **Architecture**: See [Help System Fluent Integration (ADR-018)](../architecture/adr/adr-018-help-system-fluent-integration.md)\n- **Language Guidelines**: See development documentation for language-specific guidelines\n- **Fluent Documentation**: [Mozilla Fluent](https://projectfluent.org/)\n\n## Future Enhancements\n\n### Planned Features\n\n1. **Auto-Loading**: Detect available languages and load dynamically\n2. **Language Metadata**: Store language names, native names, RTL support\n3. **Pluralization**: Support for plural forms (1 item, 2+ items)\n4. **Date/Time Formatting**: Locale-aware date, time, and number formatting\n5. **Translation Coverage**: Automated reports of translation completeness\n\n### Long-Term Vision\n\n- Full i18n support across provisioning system\n- Web-based translation interface for external contributors\n- Community translation workflow with Git integration\n- Real-time language switching without restart\n\n---\n\n**Last Updated**: January 2026\n**Version**: 1.0\n**Status**: Active
