provisioning/locales/TRANSLATIONS_STATUS.md

# Multilingual Provisioning System - Translation Status

**Last Updated**: 2026-01-13
**Status**: 100% Complete (Phases 1-4D)

## Executive Summary

The Provisioning system now supports comprehensive multilingual interfaces across all components:

- **Help System**: 65 strings extracted and translated
- **Forms**: ~180 strings covering setup, authentication, and infrastructure management
- **Supported Languages**: English (en-US), Spanish (es-ES) with infrastructure for future additions

## Language Coverage

### English (en-US) - 100% Complete ✅

**Source of Truth**: `/provisioning/locales/en-US/`

| Component | File | Strings | Status |
|-----------|------|---------|--------|
| Help System | `help.ftl` | 65 | ✅ Complete |
| Forms | `forms.ftl` | 180 | ✅ Complete |
| **Total** | | **245** | **✅ Complete** |

### Spanish (es-ES) - 100% Complete ✅

**Source of Truth**: `/provisioning/locales/es-ES/`

| Component | File | Strings | Status |
|-----------|------|---------|--------|
| Help System | `help.ftl` | 65 | ✅ Complete |
| Forms | `forms.ftl` | 180 | ✅ Complete |
| **Total** | | **245** | **✅ Complete** |

## String Breakdown by Category

### Help System (65 strings)

**Main Menu** (26 strings):
- Title, subtitle, category hint
- 13 category names and descriptions (infrastructure, orchestration, development, workspace, platform, setup, authentication, plugins, utilities, tools, vm, diagnostics, concepts, guides, integrations)
- 3 error messages

**Infrastructure** (21 strings):
- Section title
- Server operations (4 strings)
- TaskServ management (4 strings)
- Cluster management (4 strings)
- VM operations (4 strings)
- Infrastructure tip

**Orchestration** (18 strings):
- Section title
- Orchestrator management (5 strings)
- Workflow operations (5 strings)
- Batch operations (7 strings)
- Batch workflows tip + example

### Forms (180 strings)

**Unified Setup Form** (~140 strings):
- Project information (project name, version, description)
- Database configuration (PostgreSQL, MySQL, MongoDB, SQLite)
- API service configuration (name, ports, health check, replicas)
- Deployment options (Docker Compose, Kubernetes, Cloud)
- Advanced options (monitoring, TLS)
- Security & authentication (JWT, OAuth2, SAML, None)
- Terms & conditions (terms, newsletter, save address)

**Core Forms** (~40 strings):
- Auth login form (username, password, remember me, forgot password)
- Setup wizard (quick, standard, advanced)
- MFA enrollment (TOTP, SMS, backup codes, device name)

**Infrastructure Forms** (interactive):
- Delete confirmations (30+ potential variations for different resources)
- Resource confirmation prompts
- Data retention options

## TypeDialog Integration

### Configured Forms

The following root forms have `locales_path` configured to use Fluent catalogs:

| Form | Path | locales_path |
|------|------|--------------|
| Unified Setup | `.typedialog/provisioning/form.toml` | `../../../locales` |
| CI Configuration | `.typedialog/ci/form.toml` | `../../../locales` |
| Core Auth | `.typedialog/core/forms/auth-login.toml` | `../../../../../locales` |
| Core Setup Wizard | `.typedialog/core/forms/setup-wizard.toml` | `../../../../../locales` |
| Core MFA | `.typedialog/core/forms/mfa-enroll.toml` | `../../../../../locales` |

**Note**: Fragment forms (70+ files) inherit locales from their parent forms through TypeDialog's `load_fragments` mechanism.

## Fluent File Organization

```bash
provisioning/locales/
├── i18n-config.toml                 # Central i18n configuration
├── TRANSLATIONS_STATUS.md           # This file
├── 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
```

## Fallback Chains

When a string is missing in the active locale, TypeDialog automatically falls back to the configured chain:

```toml
es-ES → en-US (default)
```

**Configuration** in `i18n-config.toml`:
```toml
[fallback_chains]
es-ES = ["en-US"]
```

This ensures that if any Spanish translation is missing, the English version is displayed as a fallback.

## Feature Configuration

The i18n system supports these features (enabled in `i18n-config.toml`):

| Feature | Status | Purpose |
|---------|--------|---------|
| Pluralization | ✅ Enabled | Support plural forms in translations |
| Number Formatting | ✅ Enabled | Locale-specific number/currency formatting |
| Date Formatting | ✅ Enabled | Locale-specific date formats |
| Fallback Chains | ✅ Enabled | Automatic fallback to English |
| Gender Agreement | ⚠️ Disabled | Spanish doesn't need gender in these strings |
| RTL Support | ⚠️ Disabled | No RTL languages configured yet |

## Translation Quality Standards

### Naming Conventions

All Fluent keys follow a consistent pattern:

- **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

From `i18n-config.toml`:

- **Required Coverage**: 95% (critical locales: en-US, es-ES)
- **Warning Threshold**: 80%
- **Validation**: Missing keys trigger warnings during build

## Testing & Validation

### Locale Resolution

The system uses the `LANG` environment variable for locale selection:

```bash
# English (default)
$ LANG=en_US provisioning help infrastructure
# Output: SERVER & INFRASTRUCTURE...

# Spanish
$ LANG=es_ES provisioning help infrastructure
# Output: SERVIDOR E INFRAESTRUCTURA...

# Fallback to English if missing locale file
$ LANG=fr_FR provisioning help infrastructure
# Output: SERVER & INFRASTRUCTURE... (fallback)
```

### Form Testing

TypeDialog forms automatically use the configured locale:

```toml
# Display Unified Setup in English
$ LANG=en_US provisioning setup profile

# Display Unified Setup in Spanish
$ LANG=es_ES provisioning setup profile
```

### Coverage Validation

To validate translation coverage:

```bash
# Check translation status
provisioning i18n status

# Generate coverage report
provisioning i18n coverage --locale es-ES
# Expected: 100% (245/245 strings translated)

# Validate Fluent files
provisioning i18n validate
```

## Future Expansion

The infrastructure supports adding new languages. To add a new locale (e.g., Portuguese):

### 1. Add Locale Configuration

In `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"]
```

### 2. Create Locale Directory

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

### 3. Create Translation Files

```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

Update `pt-BR/help.ftl` and `pt-BR/forms.ftl` with Portuguese translations.

### 5. Validate

```bash
provisioning i18n validate --locale pt-BR
```

## Architecture & Implementation Details

### Mozilla Fluent Format

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

- **Simple Syntax**: `key = value` format
- **Rich Features**: Pluralization, gender agreement, attributes
- **Fallback Support**: Automatic chain resolution
- **Extensibility**: Support for custom functions and formatting

**Example**:
```bash
help-infra-server-create = Create a new server
form-database_type-option-postgres = PostgreSQL (Recommended)
```

### TypeDialog Integration

TypeDialog forms reference Fluent keys via `locales_path`:

```bash
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"
```

TypeDialog's locale resolution:

1. Check `locales_path` configuration
2. Look for `LANG` environment variable (e.g., `es_ES`)
3. Find corresponding Fluent file (e.g., `es-ES/forms.ftl`)
4. Resolve key → value
5. Fallback to parent locale chain if missing
6. Use literal key if no translation found

## Coverage Metrics

### String Count Summary

| Category | en-US | es-ES | Coverage |
|----------|-------|-------|----------|
| Help System | 65 | 65 | 100% ✅ |
| Forms | 180 | 180 | 100% ✅ |
| **Total** | **245** | **245** | **100%** ✅ |

### Language Support

| Locale | Strings | Status | Notes |
|--------|---------|--------|-------|
| en-US | 245 | ✅ Complete | Base language |
| es-ES | 245 | ✅ Complete | Full translation |
| pt-BR | - | 🔄 Planned | Infrastructure ready |
| fr-FR | - | 🔄 Planned | Infrastructure ready |
| ja-JP | - | 🔄 Planned | Infrastructure ready |

## Maintenance & Updates

### Adding Translations

When new forms or help sections are added:

1. Extract strings using extraction tools
2. Add Fluent keys to `en-US/*.ftl`
3. Translate to `es-ES/*.ftl`
4. Update this status document

### Validation Checklist

- [ ] All new strings have Fluent keys
- [ ] Keys follow naming conventions
- [ ] English translation complete
- [ ] Spanish translation complete
- [ ] Fallback chains tested
- [ ] LANG environment variable works
- [ ] TypeDialog forms display correctly

## References

- **Fluent Documentation**: https://projectfluent.org/
- **TypeDialog i18n**: TypeDialog embedded documentation
- **i18n Configuration**: See `provisioning/locales/i18n-config.toml`
- **Help System**: See `provisioning/core/nulib/main_provisioning/help_system.nu`

---

**Status**: ✅ Complete
**Phases Completed**: 1, 2, 3, 4A, 4B, 4C, 4D
**Ready for**: Production deployment, further language additions, testing