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:

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

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

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

$ 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.

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

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

[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

mkdir -p provisioning/locales/pt-BR

3. Create Translation Files

Copy English files as base:

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:

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

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

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

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

# 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 - Configure Provisioning after installation
• Workspace Management - Workspace configuration and usage
• Design Principles - Architecture and design
• API Reference - CLI commands and help system