2 lines
10 KiB
Markdown
2 lines
10 KiB
Markdown
# Multilingual Provisioning System - Translation Status\n\n**Last Updated**: 2026-01-13\n**Status**: 100% Complete (Phases 1-4D)\n\n## Executive Summary\n\nThe Provisioning system now supports comprehensive multilingual interfaces across all components:\n\n- **Help System**: 65 strings extracted and translated\n- **Forms**: ~180 strings covering setup, authentication, and infrastructure management\n- **Supported Languages**: English (en-US), Spanish (es-ES) with infrastructure for future additions\n\n## Language Coverage\n\n### English (en-US) - 100% Complete ✅\n\n**Source of Truth**: `/provisioning/locales/en-US/`\n\n| Component | File | Strings | Status |\n|-----------|------|---------|--------|\n| Help System | `help.ftl` | 65 | ✅ Complete |\n| Forms | `forms.ftl` | 180 | ✅ Complete |\n| **Total** | | **245** | **✅ Complete** |\n\n### Spanish (es-ES) - 100% Complete ✅\n\n**Source of Truth**: `/provisioning/locales/es-ES/`\n\n| Component | File | Strings | Status |\n|-----------|------|---------|--------|\n| Help System | `help.ftl` | 65 | ✅ Complete |\n| Forms | `forms.ftl` | 180 | ✅ Complete |\n| **Total** | | **245** | **✅ Complete** |\n\n## String Breakdown by Category\n\n### Help System (65 strings)\n\n**Main Menu** (26 strings):\n- Title, subtitle, category hint\n- 13 category names and descriptions (infrastructure, orchestration, development, workspace, platform, setup, authentication, plugins, utilities, tools, vm, diagnostics, concepts, guides, integrations)\n- 3 error messages\n\n**Infrastructure** (21 strings):\n- Section title\n- Server operations (4 strings)\n- TaskServ management (4 strings)\n- Cluster management (4 strings)\n- VM operations (4 strings)\n- Infrastructure tip\n\n**Orchestration** (18 strings):\n- Section title\n- Orchestrator management (5 strings)\n- Workflow operations (5 strings)\n- Batch operations (7 strings)\n- Batch workflows tip + example\n\n### Forms (180 strings)\n\n**Unified Setup Form** (~140 strings):\n- Project information (project name, version, description)\n- Database configuration (PostgreSQL, MySQL, MongoDB, SQLite)\n- API service configuration (name, ports, health check, replicas)\n- Deployment options (Docker Compose, Kubernetes, Cloud)\n- Advanced options (monitoring, TLS)\n- Security & authentication (JWT, OAuth2, SAML, None)\n- Terms & conditions (terms, newsletter, save address)\n\n**Core Forms** (~40 strings):\n- Auth login form (username, password, remember me, forgot password)\n- Setup wizard (quick, standard, advanced)\n- MFA enrollment (TOTP, SMS, backup codes, device name)\n\n**Infrastructure Forms** (interactive):\n- Delete confirmations (30+ potential variations for different resources)\n- Resource confirmation prompts\n- Data retention options\n\n## TypeDialog Integration\n\n### Configured Forms\n\nThe following root forms have `locales_path` configured to use Fluent catalogs:\n\n| Form | Path | locales_path |\n|------|------|--------------|\n| Unified Setup | `.typedialog/provisioning/form.toml` | `../../../locales` |\n| CI Configuration | `.typedialog/ci/form.toml` | `../../../locales` |\n| Core Auth | `.typedialog/core/forms/auth-login.toml` | `../../../../../locales` |\n| Core Setup Wizard | `.typedialog/core/forms/setup-wizard.toml` | `../../../../../locales` |\n| Core MFA | `.typedialog/core/forms/mfa-enroll.toml` | `../../../../../locales` |\n\n**Note**: Fragment forms (70+ files) inherit locales from their parent forms through TypeDialog's `load_fragments` mechanism.\n\n## Fluent File Organization\n\n```\nprovisioning/locales/\n├── i18n-config.toml # Central i18n configuration\n├── TRANSLATIONS_STATUS.md # This file\n├── en-US/ # English base language\n│ ├── help.ftl # Help system strings (65 keys)\n│ └── forms.ftl # Form strings (180 keys)\n└── es-ES/ # Spanish translations\n ├── help.ftl # Help system translations\n └── forms.ftl # Form translations\n```\n\n## Fallback Chains\n\nWhen a string is missing in the active locale, TypeDialog automatically falls back to the configured chain:\n\n```\nes-ES → en-US (default)\n```\n\n**Configuration** in `i18n-config.toml`:\n```\n[fallback_chains]\nes-ES = ["en-US"]\n```\n\nThis ensures that if any Spanish translation is missing, the English version is displayed as a fallback.\n\n## Feature Configuration\n\nThe i18n system supports these features (enabled in `i18n-config.toml`):\n\n| Feature | Status | Purpose |\n|---------|--------|---------|\n| Pluralization | ✅ Enabled | Support plural forms in translations |\n| Number Formatting | ✅ Enabled | Locale-specific number/currency formatting |\n| Date Formatting | ✅ Enabled | Locale-specific date formats |\n| Fallback Chains | ✅ Enabled | Automatic fallback to English |\n| Gender Agreement | ⚠️ Disabled | Spanish doesn't need gender in these strings |\n| RTL Support | ⚠️ Disabled | No RTL languages configured yet |\n\n## Translation Quality Standards\n\n### Naming Conventions\n\nAll Fluent keys follow a consistent pattern:\n\n- **Help strings**: `help-{category}-{element}` (e.g., `help-infra-server-create`)\n- **Form prompts**: `form-{element}-prompt` (e.g., `form-project_name-prompt`)\n- **Form help**: `form-{element}-help` (e.g., `form-project_name-help`)\n- **Form placeholders**: `form-{element}-placeholder`\n- **Form options**: `form-{element}-option-{value}` (e.g., `form-database_type-option-postgres`)\n- **Section headers**: `section-{name}-title`\n\n### Coverage Requirements\n\nFrom `i18n-config.toml`:\n\n- **Required Coverage**: 95% (critical locales: en-US, es-ES)\n- **Warning Threshold**: 80%\n- **Validation**: Missing keys trigger warnings during build\n\n## Testing & Validation\n\n### Locale Resolution\n\nThe system uses the `LANG` environment variable for locale selection:\n\n```\n# English (default)\n$ LANG=en_US provisioning help infrastructure\n# Output: SERVER & INFRASTRUCTURE...\n\n# Spanish\n$ LANG=es_ES provisioning help infrastructure\n# Output: SERVIDOR E INFRAESTRUCTURA...\n\n# Fallback to English if missing locale file\n$ LANG=fr_FR provisioning help infrastructure\n# Output: SERVER & INFRASTRUCTURE... (fallback)\n```\n\n### Form Testing\n\nTypeDialog forms automatically use the configured locale:\n\n```\n# Display Unified Setup in English\n$ LANG=en_US provisioning setup profile\n\n# Display Unified Setup in Spanish\n$ LANG=es_ES provisioning setup profile\n```\n\n### Coverage Validation\n\nTo validate translation coverage:\n\n```\n# Check translation status\nprovisioning i18n status\n\n# Generate coverage report\nprovisioning i18n coverage --locale es-ES\n# Expected: 100% (245/245 strings translated)\n\n# Validate Fluent files\nprovisioning i18n validate\n```\n\n## Future Expansion\n\nThe infrastructure supports adding new languages. To add a new locale (e.g., Portuguese):\n\n### 1. Add Locale Configuration\n\nIn `i18n-config.toml`:\n\n```\n[locales.pt-BR]\nname = "Portuguese (Brazil)"\ndirection = "ltr"\nplurals = 2\ndecimal_separator = ","\nthousands_separator = "."\ndate_format = "DD/MM/YYYY"\n\n[fallback_chains]\npt-BR = ["pt-PT", "es-ES", "en-US"]\n```\n\n### 2. Create Locale Directory\n\n```\nmkdir -p provisioning/locales/pt-BR\n```\n\n### 3. Create Translation Files\n\n```\ncp provisioning/locales/en-US/help.ftl provisioning/locales/pt-BR/help.ftl\ncp provisioning/locales/en-US/forms.ftl provisioning/locales/pt-BR/forms.ftl\n```\n\n### 4. Translate Strings\n\nUpdate `pt-BR/help.ftl` and `pt-BR/forms.ftl` with Portuguese translations.\n\n### 5. Validate\n\n```\nprovisioning i18n validate --locale pt-BR\n```\n\n## Architecture & Implementation Details\n\n### Mozilla Fluent Format\n\nAll translations use Mozilla Fluent (.ftl files), which offers:\n\n- **Simple Syntax**: `key = value` format\n- **Rich Features**: Pluralization, gender agreement, attributes\n- **Fallback Support**: Automatic chain resolution\n- **Extensibility**: Support for custom functions and formatting\n\n**Example**:\n```\nhelp-infra-server-create = Create a new server\nform-database_type-option-postgres = PostgreSQL (Recommended)\n```\n\n### TypeDialog Integration\n\nTypeDialog forms reference Fluent keys via `locales_path`:\n\n```\nlocales_path = "../../../locales"\n\n[[elements]]\nname = "project_name"\nprompt = "form-project_name-prompt" # References: locales/*/forms.ftl\nhelp = "form-project_name-help"\nplaceholder = "form-project_name-placeholder"\n```\n\nTypeDialog's locale resolution:\n\n1. Check `locales_path` configuration\n2. Look for `LANG` environment variable (e.g., `es_ES`)\n3. Find corresponding Fluent file (e.g., `es-ES/forms.ftl`)\n4. Resolve key → value\n5. Fallback to parent locale chain if missing\n6. Use literal key if no translation found\n\n## Coverage Metrics\n\n### String Count Summary\n\n| Category | en-US | es-ES | Coverage |\n|----------|-------|-------|----------|\n| Help System | 65 | 65 | 100% ✅ |\n| Forms | 180 | 180 | 100% ✅ |\n| **Total** | **245** | **245** | **100%** ✅ |\n\n### Language Support\n\n| Locale | Strings | Status | Notes |\n|--------|---------|--------|-------|\n| en-US | 245 | ✅ Complete | Base language |\n| es-ES | 245 | ✅ Complete | Full translation |\n| pt-BR | - | 🔄 Planned | Infrastructure ready |\n| fr-FR | - | 🔄 Planned | Infrastructure ready |\n| ja-JP | - | 🔄 Planned | Infrastructure ready |\n\n## Maintenance & Updates\n\n### Adding Translations\n\nWhen new forms or help sections are added:\n\n1. Extract strings using extraction tools\n2. Add Fluent keys to `en-US/*.ftl`\n3. Translate to `es-ES/*.ftl`\n4. Update this status document\n\n### Validation Checklist\n\n- [ ] All new strings have Fluent keys\n- [ ] Keys follow naming conventions\n- [ ] English translation complete\n- [ ] Spanish translation complete\n- [ ] Fallback chains tested\n- [ ] LANG environment variable works\n- [ ] TypeDialog forms display correctly\n\n## References\n\n- **Fluent Documentation**: https://projectfluent.org/\n- **TypeDialog i18n**: TypeDialog embedded documentation\n- **i18n Configuration**: See `provisioning/locales/i18n-config.toml`\n- **Help System**: See `provisioning/core/nulib/main_provisioning/help_system.nu`\n\n---\n\n**Status**: ✅ Complete\n**Phases Completed**: 1, 2, 3, 4A, 4B, 4C, 4D\n**Ready for**: Production deployment, further language additions, testing\n
|