workforce-pay-bill-p/TRANSLATION_PRELOADING.md

Translation Preloading System

Overview

All translation files are preloaded on initial app load to enable instant language switching without any visible "flash of untranslated content" (FOUC).

How It Works

1. Preload Phase (App Initialization)

When the app first loads, useLocaleInit() is called which:

• Loads all translation files (en.json, es.json, fr.json) in parallel
• Caches them in memory using a shared translationsCache Map
• Only shows the app once all translations are loaded and cached
• Sets translationsReady flag in Redux to signal completion

2. Translation Hook Usage

Components using useTranslation() will:

• Always read from the in-memory cache (instant access)
• Never cause loading states or re-renders when switching languages
• Fall back to English if a translation is missing

3. Language Switching

When users switch languages:

• The translation is already in memory from the preload phase
• Redux updates the current locale
• Components re-render immediately with the new translations
• No loading indicators, no delays, no FOUC

Key Files

/src/hooks/use-locale-init.ts

Preloads all translations on app startup using preloadAllTranslations().

/src/hooks/use-translation.ts

• Exports preloadAllTranslations() for initial loading
• Manages the shared translationsCache Map
• Provides useTranslation() hook for components
• Provides useChangeLocale() for language switching

/src/hooks/use-translation-cache.ts

Legacy cache hook - now uses dynamic imports instead of fetch for better bundling.

Benefits

1. No FOUC: Users never see translation keys or partial translations
2. Instant Switching: Language changes are immediate with no loading state
3. Better UX: Smooth experience with loading indicator on initial load
4. Efficient Caching: All translations loaded once and reused throughout session
5. Fallback Support: Automatic fallback to English if translation missing

Usage Example

import { useTranslation } from '@/hooks/use-translation'

function MyComponent() {
  const { t, locale, changeLocale } = useTranslation()
  
  return (
    <div>
      <h1>{t('dashboard.title')}</h1>
      <button onClick={() => changeLocale('es')}>
        Switch to Spanish (instant!)
      </button>
    </div>
  )
}

Performance

• Initial load: ~100-300ms (all 3 translation files loaded in parallel)
• Language switch: ~0ms (reads from cache)
• Memory usage: ~50-100KB per translation file (minimal)

Adding New Languages

1. Create new translation file: /src/data/translations/de.json
2. Add locale to AVAILABLE_LOCALES array in use-translation.ts
3. Add type to Locale type union
4. Translations will be automatically preloaded on next app load