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

   new-feature = This is a new feature
   

2. Mark as untranslated in other locales:

   new-feature = [NEEDS TRANSLATION]
   

3. Translate and remove marker:

   new-feature = Ceci est une nouvelle fonctionnalité
   

4. Verify coverage:

   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

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