Internationalization

Internationalization (i18n)

CAAL supports multiple languages across all components: voice pipeline (STT, LLM, TTS), web frontend, and mobile app.

Supported Languages

Code	Language	Frontend	Mobile	Voice (STT/TTS)	Prompts
en	English	✅	✅	✅	✅
fr	French	✅	✅	✅	✅
it	Italian	✅	✅	✅	✅

How It Works

Language is a single global setting. Changing it in any client propagates everywhere:

settings.json (language: "fr")
    |
    +-- Frontend: CAAL_LOCALE cookie → next-intl → French UI
    +-- Mobile: LocaleProvider → Flutter intl → French UI
    +-- Voice Agent:
            +-- STT: language="fr" → Whisper
            +-- LLM: prompt/fr/default.md → French system prompt
            +-- TTS: Piper siwis-medium → French voice
            +-- Wake greetings: prompt/fr/greetings.txt
            +-- Date/time: French formatting

First Launch

A language selector appears before the setup wizard so the entire setup experience is in the user's preferred language.

Changing Language Later

Open Settings → Agent tab → Language dropdown. The page reloads in the new language. The voice agent picks up the change on the next session.

Voice Pipeline

When a session starts, the language setting controls:

• STT — language param passed to Whisper for better transcription
• System Prompt — Loaded from prompt/{language}/default.md
• TTS Voice — Piper voice selected from PIPER_VOICE_MAP (auto-switches from Kokoro for non-English)
• Wake Greetings — Loaded from prompt/{language}/greetings.txt (one per line, editable in Settings)
• Date/Time — Localized formatting injected into the system prompt context

Adding a New Language

See the full step-by-step guide in the i18n documentation.

Quick Checklist

#	What	Where
1	System prompt	prompt/{lang}/default.md
2	Wake greetings	prompt/{lang}/greetings.txt
3	Piper voice mapping	src/caal/settings.py → PIPER_VOICE_MAP
4	Date/time formatting	src/caal/utils/formatting.py
5	Locale config	frontend/src/i18n/config.ts → locales
6	UI translations	frontend/messages/{lang}.json
7	Language dropdowns	settings-panel.tsx + language-selector.tsx → LANGUAGES
8	Piper model maps	language-selector.tsx + settings-panel.tsx
9	Mobile translations	mobile/lib/l10n/app_{lang}.arb
10	Mobile locale support	locale_provider.dart + settings_screen.dart