97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
# 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*
|