# Phase 7: Multilanguage - Context

**Gathered:** 2026-03-25
**Status:** Ready for planning

<domain>
## Phase Boundary

Full English, Spanish, and Portuguese support across the entire platform. Two surfaces: portal UI localization (all pages, labels, buttons, errors, templates, emails) and AI Employee language handling (auto-detect and respond in user's language). Extensible architecture so future languages require only translation files.

</domain>

<decisions>
## Implementation Decisions

### Language Switcher
- Default language: auto-detect from browser locale (e.g., es-MX → Spanish, pt-BR → Portuguese)
- Switcher location: sidebar bottom, near user avatar — always accessible
- Language preference: saved to portal_users table in DB — follows user across devices
- Login page: has its own language switcher (uses browser locale before auth, cookie for pre-auth persistence)
- Supported languages for v1: en (English), es (Spanish), pt (Portuguese)

### AI Employee Language Handling
- Auto-detect from each incoming message — agent responds in the same language the user writes in
- Applies across ALL channels: Slack, WhatsApp, Web Chat — consistent behavior everywhere
- Fluid switching: agent follows each individual message's language, not locked to first message
- Implementation: system prompt instruction to detect and mirror the user's language
- No per-agent language config in v1 — auto-detect is the only mode

### Translation Scope
- **Portal UI**: All pages, labels, buttons, navigation, placeholders, tooltips — fully translated
- **Agent templates**: Names, descriptions, and personas translated in all 3 languages (DB seed data includes translations)
- **Wizard steps**: All 5 wizard steps and review page fully translated
- **Onboarding flow**: All 3 onboarding steps translated
- **Error messages**: Validation text and error messages localized on the frontend
- **Invitation emails**: Sent in the language the inviting admin is currently using
- **System notifications**: Localized to match user's language preference

### Claude's Discretion
- i18n library choice (next-intl, next-i18next, or built-in Next.js i18n)
- Translation file format (JSON, TypeScript, etc.)
- Backend error message strategy (frontend-only translation recommended — cleaner separation)
- How template translations are stored in DB (JSON column vs separate translations table)
- RTL support (not needed for en/es/pt but architecture should not block it)
- Date/number formatting per locale

</decisions>

<specifics>
## Specific Ideas

- The language switcher should show flag icons or language abbreviations (EN / ES / PT) — instantly recognizable
- Templates in Spanish and Portuguese should feel native, not machine-translated — proper business terminology for each locale
- The system prompt language instruction should be concise: "Respond in the same language the user writes in. You support English, Spanish, and Portuguese."

</specifics>

<code_context>
## Existing Code Insights

### Reusable Assets
- `packages/portal/app/layout.tsx` — Root layout where i18n provider would wrap the app
- `packages/portal/components/nav.tsx` — Sidebar where language switcher goes (near user section)
- `packages/portal/components/session-sync.tsx` — Could sync language preference alongside RBAC headers
- `packages/shared/shared/models/auth.py:PortalUser` — Needs `language` field (en/es/pt)
- `packages/shared/shared/prompts/system_prompt_builder.py` — Needs language instruction appended
- `packages/portal/lib/system-prompt-builder.ts` — TypeScript mirror, same change
- `packages/shared/shared/email.py` — Email sender needs to use translated templates
- `migrations/versions/007_agent_templates.py` — Template seed data needs translated versions

### Established Patterns
- Portal uses Tailwind v4, shadcn/ui, DM Sans font (all support Latin character sets for en/es/pt)
- Auth.js v5 JWT carries user claims — could include `language` claim
- Agent templates stored as DB seed data — translations could go in same table or separate
- All UI strings are currently hardcoded in TSX — need extraction to translation files

### Integration Points
- Every portal page and component needs string extraction
- Agent Designer form labels need translation
- Template gallery card content needs translation
- Chat interface messages (system UI, not agent responses) need translation
- Error messages from API (currently English) — frontend should translate display text

</code_context>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 07-multilanguage*
*Context gathered: 2026-03-25*