provisioning/docs/src/features/multilingual-support.md

# Multilingual Support

Provisioning includes comprehensive multilingual support for help text, forms, and
interactive interfaces. The system uses Mozilla Fluent for translations with automatic
fallback chains.

## Supported Languages

Currently supported with 100% translation coverage:

| Language | Locale | Status | Strings |
| --- | --- | --- | --- |
| English (US) | en-US | ✅ Complete | 245 |
| Spanish (Spain) | es-ES | ✅ Complete | 245 |
| Portuguese (Brazil) | pt-BR | 🔄 Planned | - |
| French (France) | fr-FR | 🔄 Planned | - |
| Japanese (Japan) | ja-JP | 🔄 Planned | - |

**Coverage Requirement**: 95% of strings translated to critical locales (en-US, es-ES).

## Using Different Languages

### Setting Language via Environment Variable

Select language using the `LANG` environment variable:

```bash
# English (default)
provisioning help infrastructure

# Spanish
LANG=es_ES provisioning help infrastructure

# Fallback to English if locale not available
LANG=fr_FR provisioning help infrastructure
# Output: English (en-US) [fallback chain]
```

### Locale Resolution

Language selection follows this order:

1. Check `LANG` environment variable (e.g., `es_ES`)
2. Match to configured locale (es-ES)
3. If not found, follow fallback chain (es-ES → en-US)
4. Default to en-US if no match

**Format**: `LANG` uses underscore (es_ES), locales use hyphen (es-ES). System handles conversion automatically.

## Translation System Architecture

### Mozilla Fluent Format

All translations use Mozilla Fluent (.ftl files), which provides:

- **Simple Syntax**: Key-value pairs with rich formatting
- **Pluralization**: Support for language-specific plural rules
- **Attributes**: Multiple values per key for contextual translation
- **Automatic Fallback**: Chain resolution when keys missing
- **Extensibility**: Support for custom formatting functions

**Example Fluent syntax**:

```text
help-infra-server-create = Create a new server
form-database_type-option-postgres = PostgreSQL (Recommended)
form-replicas-prompt = Number of replicas
form-replicas-help = How many replicas to run
```

### File Organization

```text
provisioning/locales/
├── i18n-config.toml              # Central i18n configuration
├── en-US/                         # English base language
│   ├── help.ftl                  # Help system strings (65 keys)
│   └── forms.ftl                 # Form strings (180 keys)
└── es-ES/                         # Spanish translations
    ├── help.ftl                  # Help system translations
    └── forms.ftl                 # Form translations
```

**String Categories**:

- **help.ftl** (65 strings): Help text, menu items, category descriptions, error messages
- **forms.ftl** (180 strings): Form labels, placeholders, help text, options

## Help System Translations

Help system provides multi-language support for all command categories:

### Categories Covered

| Category | Coverage | Example Keys |
| --- | --- | --- |
| Infrastructure | ✅ 21 strings | server commands, taskserv, clusters, VMs |
| Orchestration | ✅ 18 strings | workflows, batch operations, orchestrator |
| Workspace | ✅ Complete | workspace management, templates |
| Setup | ✅ Complete | system configuration, initialization |
| Authentication | ✅ Complete | JWT, MFA, sessions |
| Platform | ✅ Complete | services, Control Center, MCP |
| Development | ✅ Complete | modules, versions, plugins |
| Utilities | ✅ Complete | providers, SOPS, SSH |

### Example: Help Output in Spanish

```bash
$ LANG=es_ES provisioning help infrastructure
SERVIDOR E INFRAESTRUCTURA
Gestión de servidores, taskserv, clusters, VM e infraestructura.

COMANDOS DE SERVIDOR
  server create         Crear un nuevo servidor
  server delete         Eliminar un servidor existente
  server list           Listar todos los servidores
  server status         Ver estado de un servidor

COMANDOS DE TASKSERV
  taskserv create       Crear un nuevo servicio de tarea
  taskserv delete       Eliminar un servicio de tarea
  taskserv configure    Configurar un servicio de tarea
  taskserv status       Ver estado del servicio de tarea
```

## Form Translations (TypeDialog Integration)

Interactive forms automatically use the selected language:

### Setup Form

Project information, database configuration, API settings, deployment options, security, etc.

```bash
# English form
$ provisioning setup profile
📦 Project name: [my-app]

# Spanish form
$ LANG=es_ES provisioning setup profile
📦 Nombre del proyecto: [mi-app]
```

### Translated Form Fields

Each form field has four translated strings:

| Component | Purpose | Example en-US | Example es-ES |
| --- | --- | --- | --- |
| prompt | Field label | "Project name" | "Nombre del proyecto" |
| help | Helper text | "Project name (lowercase alphanumeric with hyphens)" | "Nombre del proyecto (minúsculas alfanuméricas con guiones)" |
| placeholder | Example value | "my-app" | "mi-app" |
| option | Dropdown choice | "PostgreSQL (Recommended)" | "PostgreSQL (Recomendado)" |

### Supported Forms

- **Unified Setup**: Project info, database, API, deployment, security, terms
- **Authentication**: Login form (username, password, remember me, forgot password)
- **Setup Wizard**: Quick/standard/advanced modes
- **MFA Enrollment**: TOTP, SMS, backup codes, device management
- **Infrastructure**: Delete confirmations, resource prompts, data retention

## Fallback Chain Configuration

When a translation string is missing, the system automatically falls back to the parent locale:

```toml
# From i18n-config.toml
[fallback_chains]
es-ES = ["en-US"]
pt-BR = ["pt-PT", "es-ES", "en-US"]
fr-FR = ["en-US"]
ja-JP = ["en-US"]
```

**Resolution Example**:

1. User requests Spanish (es-ES): `provisioning help`
2. Look for string in `es-ES/help.ftl`
3. If missing, fallback to en-US (`help-infra-server-create = "Create a new server"`)
4. If still missing, use literal key name as display text

## Adding New Languages

### 1. Add Locale Configuration

Edit `provisioning/locales/i18n-config.toml`:

```toml
[locales.pt-BR]
name = "Portuguese (Brazil)"
direction = "ltr"
plurals = 2
decimal_separator = ","
thousands_separator = "."
date_format = "DD/MM/YYYY"

[fallback_chains]
pt-BR = ["pt-PT", "es-ES", "en-US"]
```

**Configuration Fields**:

- **name**: Display name of locale
- **direction**: Text direction (ltr/rtl)
- **plurals**: Number of plural forms (1-6 depending on language)
- **decimal_separator**: Locale-specific decimal format
- **thousands_separator**: Number formatting
- **date_format**: Locale-specific date format
- **currency_symbol**: Currency symbol (optional)
- **currency_position**: "prefix" or "suffix" (optional)

### 2. Create Locale Directory

```bash
mkdir -p provisioning/locales/pt-BR
```

### 3. Create Translation Files

Copy English files as base:

```bash
cp provisioning/locales/en-US/help.ftl provisioning/locales/pt-BR/help.ftl
cp provisioning/locales/en-US/forms.ftl provisioning/locales/pt-BR/forms.ftl
```

### 4. Translate Strings

Edit `pt-BR/help.ftl` and `pt-BR/forms.ftl` with translated content. Follow naming conventions:

```text
# Help strings: help-{category}-{element}
help-infra-server-create = Criar um novo servidor

# Form prompts: form-{element}-prompt
form-project_name-prompt = Nome do projeto

# Form help: form-{element}-help
form-project_name-help = Nome do projeto (alfanumérico minúsculo com hífens)

# Form options: form-{element}-option-{value}
form-database_type-option-postgres = PostgreSQL (Recomendado)
```

### 5. Validate Translation

Check coverage and syntax:

```bash
# Validate Fluent file syntax
provisioning i18n validate --locale pt-BR

# Check translation coverage
provisioning i18n coverage --locale pt-BR

# List missing translations
provisioning i18n missing --locale pt-BR
```

### 6. Update Documentation

Document new language support in translations_status.md.

## Validation & Quality Standards

### Translation Quality Rules

**Naming Conventions** (REQUIRED):

- Help strings: `help-{category}-{element}` (e.g., `help-infra-server-create`)
- Form prompts: `form-{element}-prompt` (e.g., `form-project_name-prompt`)
- Form help: `form-{element}-help` (e.g., `form-project_name-help`)
- Form placeholders: `form-{element}-placeholder`
- Form options: `form-{element}-option-{value}` (e.g., `form-database_type-option-postgres`)
- Section headers: `section-{name}-title`

**Coverage Requirements**:

- **Critical Locales**: en-US, es-ES require 95% minimum coverage
- **Warning Threshold**: 80% triggers warnings during build
- **Incomplete Locales**: 0% coverage allowed (inherit via fallback chain)

### Testing Localization

Test translations via different methods:

```bash
# Test help system in Spanish
LANG=es_ES provisioning help infrastructure

# Test form display in Spanish
LANG=es_ES provisioning setup profile

# Validate all translation files
provisioning i18n validate --all

# Generate coverage report
provisioning i18n coverage --format=json > coverage.json
```

## Implementation Details

### TypeDialog Integration

TypeDialog forms reference Fluent keys via `locales_path` configuration:

```toml
# In form.toml
locales_path = "../../../locales"

[[elements]]
name = "project_name"
prompt = "form-project_name-prompt"    # References: locales/*/forms.ftl
help = "form-project_name-help"
placeholder = "form-project_name-placeholder"
```

**Resolution Process**:

1. Read `locales_path` from form configuration
2. Check `LANG` environment variable (converted to locale format: es_ES → es-ES)
3. Load Fluent file (e.g., `locales/es-ES/forms.ftl`)
4. Resolve string key → value
5. If key missing, follow fallback chain
6. If still missing, use literal key name

### Help System Integration

Help system uses Fluent catalog loader in `provisioning/core/nulib/main_provisioning/help_system.nu`:

```nushell
# Load help strings for current locale
let help_strings = (load_fluent_catalog $locale)

# Display localized help text
print ($help_strings | get help-infrastructure-title)
```

## Maintenance

### Adding New Translations

When new help text or forms are added:

1. Add English strings to `en-US/help.ftl` or `en-US/forms.ftl`
2. Add Spanish translations to `es-ES/help.ftl` or `es-ES/forms.ftl`
3. Run validation: `provisioning i18n validate`
4. Update `translations_status.md` with new counts
5. If coverage drops below 95%, fix before release

### Updating Existing Translations

To modify existing translated string:

1. Edit key in `en-US/*.ftl` and all locale-specific files
2. Run validation to ensure consistency
3. Test in both languages: `LANG=en_US provisioning help` and `LANG=es_ES provisioning help`

## Current Translation Status

**Last Updated**: 2026-01-13 | **Status**: 100% Complete

### String Count

| Component | en-US | es-ES | Status |
| --- | --- | --- | --- |
| Help System | 65 | 65 | ✅ Complete |
| Forms | 180 | 180 | ✅ Complete |
| **Total** | **245** | **245** | **✅ Complete** |

### Features Enabled

| Feature | Status | Purpose |
| --- | --- | --- |
| Pluralization | ✅ Enabled | Support language-specific plural rules |
| Number Formatting | ✅ Enabled | Locale-specific number/currency formatting |
| Date Formatting | ✅ Enabled | Locale-specific date display |
| Fallback Chains | ✅ Enabled | Automatic fallback to English |
| Gender Agreement | ⚠️ Disabled | Not needed for Spanish help strings |
| RTL Support | ⚠️ Disabled | No RTL languages configured yet |

## Related Documentation

- [System Setup](../setup/initial-setup.md) - Configure Provisioning after installation
- [Workspace Management](./workspace-management.md) - Workspace configuration and usage
- [Design Principles](../architecture/design-principles.md) - Architecture and design
- [API Reference](../api-reference/cli-commands.md) - CLI commands and help system