Phase 7: Multilanguage - Context

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

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

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

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

<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 Ideas

None — discussion stayed within phase scope

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

4.6 KiB Raw Permalink Blame History