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

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:

es-ES → en-US (default)

Configuration in i18n-config.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:

# 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:

# 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:

# 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:

[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

mkdir -p provisioning/locales/pt-BR

3. Create Translation Files

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

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:

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:

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