TypeDialog/examples/17-advanced-i18n/translations-status.md

# Translation Coverage Status

**Last Updated**: 2025-01-12

Complete translation coverage tracking for all 9 locales in the checkout form example.

## Overall Coverage

| Locale | Code | Files | Coverage | Status | Priority |
|--------|------|-------|----------|--------|----------|
| English (US) | en-US | ✓ | 100% | Reference | - |
| English (UK) | en-GB | ✓ | 95% | 1 missing | Medium |
| Spanish (Spain) | es-ES | ✓ | 100% | Complete | High |
| Spanish (Mexico) | es-MX | ✓ | 100% | Complete | High |
| Portuguese (Brazil) | pt-BR | ✓ | 80% | Fallback chain | Medium |
| Portuguese (Portugal) | pt-PT | ✓ | 95% | 1 missing | Medium |
| French (France) | fr-FR | ✓ | 100% | Complete | High |
| Japanese (Japan) | ja-JP | ✓ | 100% | Complete | Medium |
| Arabic (Saudi Arabia) | ar-SA | ✓ | 100% | RTL support | High |

## Detailed Coverage by Key

### Order Summary Section

| Key | en-US | en-GB | es-ES | es-MX | pt-BR | pt-PT | fr-FR | ja-JP | ar-SA |
|-----|-------|-------|-------|-------|-------|-------|-------|-------|-------|
| order-items-count | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| subtotal-amount | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| tax-amount | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| shipping-cost | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| order-total | ✓ | ✓ | ✓ | ✓ | ⟵ | ✓ | ✓ | ✓ | ✓ |

**Note**: pt-BR `order-total` missing - falls back to pt-PT ✓

### Delivery Information Section

| Key | en-US | en-GB | es-ES | es-MX | pt-BR | pt-PT | fr-FR | ja-JP | ar-SA |
|-----|-------|-------|-------|-------|-------|-------|-------|-------|-------|
| recipient-title | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| delivery-greeting | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| preferred-delivery-date | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| delivery-instructions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| delivery-window | ✓ | ✓ | ✓ | ✓ | ⟵ | ✓ | ✓ | ✓ | ✓ |

**Note**: pt-BR `delivery-window` missing - falls back to pt-PT ✓

### Billing Address Section

| Key | en-US | en-GB | es-ES | es-MX | pt-BR | pt-PT | fr-FR | ja-JP | ar-SA |
|-----|-------|-------|-------|-------|-------|-------|-------|-------|-------|
| billing-country | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| payment-method | ✓ | ✓ | ✓ | ✓ | ⟵ | ✓ | ✓ | ✓ | ✓ |

**Note**: pt-BR `payment-method` missing - falls back to pt-PT ✓

### Order Review Section

| Key | en-US | en-GB | es-ES | es-MX | pt-BR | pt-PT | fr-FR | ja-JP | ar-SA |
|-----|-------|-------|-------|-------|-------|-------|-------|-------|-------|
| agree-terms | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| agree-terms-error | ✓ | ✓ | ✓ | ✓ | ⟵ | ✓ | ✓ | ✓ | ✓ |
| agree-newsletter | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| save-address-future | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

**Note**: pt-BR `agree-terms-error` missing - falls back to pt-PT ✓

### Confirmation Messages Section

| Key | en-US | en-GB | es-ES | es-MX | pt-BR | pt-PT | fr-FR | ja-JP | ar-SA |
|-----|-------|-------|-------|-------|-------|-------|-------|-------|-------|
| order-confirmed | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| order-number | ✓ | ✓ | ✓ | ✓ | ⟵ | ✓ | ✓ | ✓ | ✓ |
| estimated-delivery | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

**Note**: pt-BR `order-number` missing - falls back to pt-PT ✓

### Error Messages Section

| Key | en-US | en-GB | es-ES | es-MX | pt-BR | pt-PT | fr-FR | ja-JP | ar-SA |
|-----|-------|-------|-------|-------|-------|-------|-------|-------|-------|
| field-required | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| invalid-date | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| invalid-amount | ✓ | ✓ | ✓ | ✓ | ⟵ | ✓ | ✓ | ✓ | ✓ |

**Note**: pt-BR `invalid-amount` missing - falls back to pt-PT ✓

## Legend

- **✓** - Translated and complete in this locale
- **⟵** - Missing in this locale, will use fallback chain
- **△** - Partial translation (90-99% complete)
- **✗** - Not translated, will use default (en-US)

## Fallback Chain Behavior

### Portuguese Brazil (pt-BR) Fallback Chain

Portuguese Brazil is intentionally incomplete to demonstrate fallback chain behavior:

```
pt-BR (80% complete)
  ├─ Lookup in pt-PT (95% complete) ✓
  │  └─ If missing, lookup in es-ES (100% complete) ✓
  │     └─ If missing, lookup in en-US (100% complete) ✓
  │        └─ Return string (or error if not found)
```

**Demonstration**:
1. `order-total` not in pt-BR → Falls back to pt-PT ✓
2. If it were missing from pt-PT, would check es-ES ✓
3. If missing from es-ES, would check en-US ✓

This shows graceful degradation - users always get *something* in a related language rather than an error.

## Translation Features Implemented

### Pluralization Rules

| Locale | Forms | Examples |
|--------|-------|----------|
| en-US | 2 | 1 item / N items |
| en-GB | 2 | 1 item / N items |
| es-ES | 2 | 1 artículo / N artículos |
| es-MX | 2 | 1 artículo / N artículos |
| pt-BR | 2 | 1 item / N itens |
| pt-PT | 2 | 1 artigo / N artigos |
| fr-FR | 3 | 0 articles / 1 article / N articles |
| ja-JP | 1 | N個のアイテム (no plural distinction) |
| ar-SA | 6 | 0 / 1 / 2 / 3-10 / 11-99 / 100+ forms |

### Gender Agreement

| Locale | Support | Examples |
|--------|---------|----------|
| en-US | ❌ | No gender marking |
| en-GB | ❌ | No gender marking |
| es-ES | ✓ | Bienvenido/Bienvenida |
| es-MX | ✓ | Bienvenido/Bienvenida |
| pt-BR | ✓ | Bem-vindo/Bem-vinda |
| pt-PT | ✓ | Bem-vindo/Bem-vinda |
| fr-FR | ✓ | Bienvenu/Bienvenue |
| ja-JP | ❌ | No gender marking in Japanese |
| ar-SA | ✓ | السيد/السيدة (Sir/Madam) |

### Number Formatting

| Locale | Format | Example |
|--------|--------|---------|
| en-US | Comma thousands, period decimal | 1,234.56 |
| en-GB | Comma thousands, period decimal | 1,234.56 |
| es-ES | Period thousands, comma decimal | 1.234,56 |
| es-MX | Comma thousands, period decimal | 1,234.56 |
| pt-BR | Period thousands, comma decimal | 1.234,56 |
| pt-PT | Period thousands, comma decimal | 1.234,56 |
| fr-FR | Period thousands, comma decimal | 1.234,56 |
| ja-JP | Comma thousands, no decimals | 1,234 |
| ar-SA | Arabic-Indic numerals | ١٬٢٣٤٫٥٦ |

### Date Formatting

| Locale | Format | Example |
|--------|--------|---------|
| en-US | MM/DD/YYYY | 1/15/2025 |
| en-GB | DD/MM/YYYY | 15/01/2025 |
| es-ES | DD/MM/YYYY | 15/01/2025 |
| es-MX | DD/MM/YYYY | 15/01/2025 |
| pt-BR | DD/MM/YYYY | 15/01/2025 |
| pt-PT | DD/MM/YYYY | 15/01/2025 |
| fr-FR | DD MMMM YYYY | 15 janvier 2025 |
| ja-JP | YYYY年M月D日 | 2025年1月15日 |
| ar-SA | DD MMMM YYYY | ١٥ يناير ٢٠٢٥ |

### Text Direction

| Locale | Direction | Support |
|--------|-----------|---------|
| en-US | LTR | ✓ Standard |
| en-GB | LTR | ✓ Standard |
| es-ES | LTR | ✓ Standard |
| es-MX | LTR | ✓ Standard |
| pt-BR | LTR | ✓ Standard |
| pt-PT | LTR | ✓ Standard |
| fr-FR | LTR | ✓ Standard |
| ja-JP | LTR | ✓ Standard |
| ar-SA | RTL | ✓ Right-to-left with `.direction = rtl` |

## Translation Maintenance Notes

### Adding a New String

1. **Add to en-US first** (reference locale):
   ```fluent
   new-feature = This is a new feature
   ```

2. **Mark as untranslated in other locales**:
   ```fluent
   new-feature = [NEEDS TRANSLATION]
   ```

3. **Translate and remove marker**:
   ```fluent
   new-feature = Ceci est une nouvelle fonctionnalité
   ```

4. **Verify coverage**:
   ```bash
   grep -r "NEEDS TRANSLATION" locales/
   ```

### Updating an Existing Translation

1. Edit the string in the appropriate locale file
2. Test in that locale: `LANG=es_ES cargo run -p typedialog-tui -- checkout-form.toml`
3. Verify plural forms work correctly (test with count=0, 1, 2, 5, 100)
4. Update translations-status.md if coverage changed

### Testing Translations

```bash
# Run all locales
./test-locales.sh

# Run specific locale
LANG=ja_JP cargo run -p typedialog-tui -- checkout-form.toml

# Validate Fluent syntax
for file in locales/*/main.ftl; do
  echo "Checking $file..."
  # Your Fluent validator here
done
```

## Next Steps for Completion

1. **Add more locales** - Use these 9 as templates for additional languages
2. **Extract UI strings** - Audit forms for hardcoded text
3. **Set up translation platform** - Crowdin, Weblate, or similar for remote teams
4. **Automate testing** - Run `test-locales.sh` in CI/CD pipeline
5. **Monitor in production** - Track translation quality and user feedback

## Key Takeaways

- **Pluralization is complex** - Arabic has 6 forms, French has special 0/1 rules, Japanese has none
- **Gender agreement varies** - Not present in English or Japanese, essential in Romance languages
- **Number/Date formatting differs** - Can't assume US format everywhere (1,234.56 vs 1.234,56)
- **RTL requires special handling** - Arabic text flows right-to-left but numbers stay left-to-right
- **Fallback chains provide resilience** - Portuguese Brazil users get Portuguese/Spanish/English if needed
- **Complete translations matter** - Mixing languages in UI breaks user experience

---

**Translation Coverage Tracking**: This document is updated whenever translation files change. Always verify the coverage matrix before deploying to production.