# Phase 7: Multilanguage - Research

**Researched:** 2026-03-25
**Domain:** i18n (Next.js portal + AI agent language detection)
**Confidence:** HIGH

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions
- 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)
- 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
- 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

### Deferred Ideas (OUT OF SCOPE)
None — discussion stayed within phase scope
</user_constraints>

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|-----------------|
| I18N-01 | Portal UI fully localized in English, Spanish, and Portuguese (all pages, labels, buttons, error messages) | next-intl v4 with JSON message files; `useTranslations` hook in all components |
| I18N-02 | Language switcher accessible from anywhere in the portal — selection persists across sessions | LanguageSwitcher component in Nav sidebar + login page; DB-backed preference via `/api/portal/users/me/language` PATCH; cookie for pre-auth state |
| I18N-03 | AI Employees detect user language and respond accordingly | System prompt language instruction appended in `build_system_prompt()` and its TS mirror |
| I18N-04 | Agent templates, wizard steps, and onboarding flow are fully translated in all three languages | JSON columns (`translations`) on `agent_templates` table; migration 009; all wizard/onboarding TSX strings extracted |
| I18N-05 | Error messages, validation text, and system notifications are localized | All Zod messages and component-level error strings extracted to message files; backend returns error codes, frontend translates |
| I18N-06 | Adding a new language requires only translation files, not code changes (extensible i18n architecture) | `SUPPORTED_LOCALES` constant + `messages/{locale}.json` file = complete new language addition |
</phase_requirements>

---

## Summary

Phase 7 adds full i18n to the Konstruct portal (Next.js 16 App Router) and language-aware behavior to AI Employees. The portal work is the largest surface area: every hardcoded English string in every TSX component needs extraction to translation JSON files. The AI Employee work is small: a single sentence appended to `build_system_prompt()`.

The recommended approach is **next-intl v4 without URL-based locale routing**. The portal's current URL structure (`/dashboard`, `/agents`, etc.) stays unchanged — locale is stored in a cookie (pre-auth) and in `portal_users.language` (post-auth). next-intl reads the correct source per request context. This is the cleanest fit because (a) the CONTEXT.md decision requires DB persistence, (b) URL-prefixed routing would require restructuring all 10+ route segments, and (c) next-intl's "without i18n routing" setup is officially documented and production-ready.

Agent template translations belong in a `translations` JSONB column on `agent_templates`. This avoids a separate join table, keeps migration simple (migration 009), and supports the extensibility requirement — adding Portuguese just adds a key to each template's JSON object.

**Primary recommendation:** Use next-intl v4 (without i18n routing) + JSON message files + JSONB template translations column + system prompt language instruction.

---

## Standard Stack

### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| next-intl | ^4.8.3 | i18n for Next.js (translations, locale detection, formatting) | Official Next.js docs recommendation; native Server Component support; proxy.ts awareness built-in; 4x smaller than next-i18next |
| next-intl/plugin | ^4.8.3 | next.config.ts integration | Required to enable `useTranslations` in Server Components |

### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| @formatjs/intl-localematcher | ^0.5.x | RFC-compliant Accept-Language matching | Proxy-level browser locale detection before auth; already in Next.js i18n docs examples |
| negotiator | ^0.6.x | HTTP Accept-Language header parsing | Pairs with @formatjs/intl-localematcher |

### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| next-intl | next-i18next | next-i18next targets Pages Router; SSR config is more complex with App Router |
| next-intl | Built-in Next.js i18n (no library) | Next.js built-in only does routing; you must build all translation utilities yourself |
| next-intl | react-i18next | Pure client-side; no Server Component support; larger bundle |
| JSONB translations column | Separate `agent_template_translations` table | Join table is cleaner at scale but overkill for 7 static templates in 3 languages |

**Installation:**
```bash
npm install next-intl @formatjs/intl-localematcher negotiator
npm install --save-dev @types/negotiator
```
(Run in `packages/portal/`)

---

## Architecture Patterns

### Recommended Project Structure

```
packages/portal/
├── messages/
│   ├── en.json          # English (source of truth)
│   ├── es.json          # Spanish
│   └── pt.json          # Portuguese
├── i18n/
│   └── request.ts       # next-intl server-side config (reads cookie + DB)
├── app/
│   ├── layout.tsx        # Wraps with NextIntlClientProvider
│   └── (dashboard)/
│       └── layout.tsx   # Already exists — add locale sync here
├── components/
│   ├── nav.tsx           # Add LanguageSwitcher near user avatar section
│   ├── language-switcher.tsx  # New component
│   └── ...
└── next.config.ts        # Add withNextIntl wrapper
```

### Pattern 1: next-intl Without URL Routing

**What:** Locale stored in cookie (pre-auth) and `portal_users.language` DB column (post-auth). No `/en/` prefix in URLs. All routes stay as-is.
**When to use:** Portal is an authenticated admin tool — SEO locale URLs have no value here. User preference follows them across devices via DB.

```typescript
// Source: https://next-intl.dev/docs/getting-started/app-router/without-i18n-routing
// i18n/request.ts
import { getRequestConfig } from 'next-intl/server';
import { cookies } from 'next/headers';

const SUPPORTED_LOCALES = ['en', 'es', 'pt'] as const;
type Locale = typeof SUPPORTED_LOCALES[number];

function isValidLocale(l: string): l is Locale {
  return (SUPPORTED_LOCALES as readonly string[]).includes(l);
}

export default getRequestConfig(async () => {
  const store = await cookies();
  const raw = store.get('locale')?.value ?? 'en';
  const locale: Locale = isValidLocale(raw) ? raw : 'en';

  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});
```

### Pattern 2: next.config.ts Plugin Integration

**What:** The next-intl SWC plugin enables `useTranslations` in Server Components.
**When to use:** Always — required for SSR-side translation.

```typescript
// Source: https://next-intl.dev/docs/getting-started/app-router/without-i18n-routing
// next.config.ts
import createNextIntlPlugin from 'next-intl/plugin';
const withNextIntl = createNextIntlPlugin('./i18n/request.ts');
export default withNextIntl({ output: 'standalone' });
```

### Pattern 3: Translation in Server and Client Components

**What:** `useTranslations` works identically in Server and Client Components. Server Components get context from `i18n/request.ts`; Client Components from `NextIntlClientProvider`.

```typescript
// Source: https://next-intl.dev/docs/environments/server-client-components

// Server Component (any page or layout — no 'use client')
import { useTranslations } from 'next-intl';
export default function DashboardPage() {
  const t = useTranslations('dashboard');
  return <h1>{t('title')}</h1>;
}

// Client Component (has 'use client')
'use client';
import { useTranslations } from 'next-intl';
export function Nav() {
  const t = useTranslations('nav');
  return <span>{t('employees')}</span>;
}
```

Root layout must wrap with `NextIntlClientProvider`:
```typescript
// app/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getLocale, getMessages } from 'next-intl/server';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const locale = await getLocale();
  const messages = await getMessages();

  return (
    <html lang={locale} ...>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}
```

**IMPORTANT:** `app/layout.tsx` is currently a Server Component. The dashboard layout `app/(dashboard)/layout.tsx` is a Client Component (`'use client'`). The `NextIntlClientProvider` must go in `app/layout.tsx` (the server root) and wrap the `body`. The dashboard layout is already inside this tree.

### Pattern 4: Language Switcher With DB Persistence

**What:** User picks language in sidebar. A Server Action (or API route) PATCHes `portal_users.language` in DB and sets the `locale` cookie. Then `router.refresh()` forces next-intl to re-read.

```typescript
// components/language-switcher.tsx
'use client';
import { useRouter } from 'next/navigation';

const LOCALES = [
  { code: 'en', label: 'EN' },
  { code: 'es', label: 'ES' },
  { code: 'pt', label: 'PT' },
] as const;

export function LanguageSwitcher() {
  const router = useRouter();

  async function handleChange(locale: string) {
    // Set cookie immediately for fast feedback
    document.cookie = `locale=${locale}; path=/; max-age=31536000`;
    // Persist to DB if authenticated
    await fetch('/api/portal/users/me/language', {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ language: locale }),
    });
    // Re-render with new locale
    router.refresh();
  }

  return (/* EN / ES / PT buttons */);
}
```

### Pattern 5: Login Page Pre-Auth Locale

**What:** Before auth, use `navigator.language` (browser API) to detect initial locale, store in cookie. Language switcher on login page only updates the cookie (no DB PATCH needed — no session yet).

```typescript
// Detect browser locale on first visit, store as cookie
const browserLocale = navigator.language.slice(0, 2); // 'es-MX' → 'es'
const supported = ['en', 'es', 'pt'];
const detected = supported.includes(browserLocale) ? browserLocale : 'en';
```

### Pattern 6: Auth.js Language Sync

**What:** On login, the `authorize()` callback fetches user from `/api/portal/auth/verify`. That endpoint should include `language` in the response. The JWT carries `language` for fast client-side access (avoids DB round-trip on every render). When user changes language, `update()` session trigger updates the JWT.

The JWT update pattern already exists for `active_tenant_id`. Language follows the same pattern.

### Pattern 7: Agent Template Translations (DB)

**What:** A `translations` JSONB column on `agent_templates` stores locale-keyed objects for name, description, and persona.

```sql
-- Migration 009 adds:
ALTER TABLE agent_templates ADD COLUMN translations JSONB NOT NULL DEFAULT '{}';

-- Example stored value:
{
  "es": {
    "name": "Representante de Atención al Cliente",
    "description": "Un agente de soporte profesional...",
    "persona": "Eres profesional, empático y orientado a soluciones..."
  },
  "pt": {
    "name": "Representante de Suporte ao Cliente",
    "description": "Um agente de suporte profissional...",
    "persona": "Você é profissional, empático e orientado a soluções..."
  }
}
```

The API endpoint `GET /api/portal/templates` should accept a `?locale=es` query param and merge translated fields before returning.

### Pattern 8: AI Employee Language Instruction

**What:** A single sentence appended to the system prompt (after the AI transparency clause or integrated before it).

```python
# packages/shared/shared/prompts/system_prompt_builder.py
LANGUAGE_INSTRUCTION = (
    "Detect the language of each user message and respond in that same language. "
    "You support English, Spanish, and Portuguese."
)
```

This is appended unconditionally to all agent system prompts — no config flag needed. The instruction is concise and effective: modern LLMs follow it reliably across Claude, GPT-4, and Ollama/Qwen models.

### Pattern 9: JSON Message File Structure

**What:** Nested JSON keyed by component/feature area. Flat keys within each namespace.

```json
// messages/en.json
{
  "nav": {
    "dashboard": "Dashboard",
    "employees": "Employees",
    "chat": "Chat",
    "usage": "Usage",
    "billing": "Billing",
    "apiKeys": "API Keys",
    "users": "Users",
    "platform": "Platform",
    "signOut": "Sign out"
  },
  "login": {
    "title": "Welcome back",
    "emailLabel": "Email",
    "passwordLabel": "Password",
    "submitButton": "Sign in",
    "invalidCredentials": "Invalid email or password. Please try again."
  },
  "agents": {
    "pageTitle": "AI Employees",
    "newEmployee": "New Employee",
    "noAgents": "No employees yet",
    "deployButton": "Deploy",
    "editButton": "Edit"
  }
  // ... one key group per page/component
}
```

### Anti-Patterns to Avoid

- **Locale in URLs for an authenticated portal:** `/en/dashboard` adds no SEO value and requires restructuring every route segment. Cookie + DB is the correct approach here.
- **Translating backend error messages:** Backend returns error codes (`"error_code": "AGENT_NOT_FOUND"`), frontend translates to display text. Backend error messages are never user-facing directly.
- **Separate translations table for 7 templates:** A `translations` JSONB column is sufficient. A join table is premature over-engineering for this use case.
- **Putting `NextIntlClientProvider` in the dashboard layout:** It must go in `app/layout.tsx` (the server root), not in the client dashboard layout, so server components throughout the tree can use `useTranslations`.
- **Using `getTranslations` in Client Components:** `getTranslations` is async and for Server Components. Client Components must use the `useTranslations` hook — they receive messages via `NextIntlClientProvider` context.
- **Hard-coding the `locale` cookie key in multiple places:** Define it as a constant (`LOCALE_COOKIE_NAME = 'konstruct_locale'`) used everywhere.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Translation lookup + fallback | Custom `t()` function | `useTranslations` (next-intl) | Missing key fallback, TypeScript key safety, pluralization rules, ICU format support |
| Browser locale negotiation | `navigator.language` + manual mapping | `@formatjs/intl-localematcher` + `negotiator` | RFC 5646 language tag parsing, quality values (q=0.9), region fallback (es-MX → es) |
| Date/number/currency formatting | `new Intl.DateTimeFormat(...)` manually | `useFormatter` (next-intl) | Consistent locale-aware formatting tied to current locale context |
| SSR hydration mismatch for locale | Manual hydration logic | next-intl `NextIntlClientProvider` | Ensures server and client render identically; prevents React hydration warnings |

**Key insight:** Translation systems have invisible complexity — plural forms, ICU message syntax, TypeScript key checking, fallback chains. next-intl handles all of these; hand-rolled solutions always miss edge cases.

---

## Common Pitfalls

### Pitfall 1: `app/layout.tsx` Is a Server Component — Don't Make It a Client Component

**What goes wrong:** Developer adds `NextIntlClientProvider` (correct) but also adds `'use client'` (wrong). This prevents the provider from reading server-side messages.
**Why it happens:** Developer sees `NextIntlClientProvider` and assumes it needs a client wrapper.
**How to avoid:** `app/layout.tsx` stays a Server Component. Call `getLocale()` and `getMessages()` (async server functions) then pass results as props to `NextIntlClientProvider`.
**Warning signs:** TypeScript error `Cannot use import statement outside a module` or translations missing in SSR output.

### Pitfall 2: `router.refresh()` vs. `router.push()` for Language Change

**What goes wrong:** Using `router.push('/')` after language change navigates to home page instead of re-rendering current page with new locale.
**Why it happens:** Developer treats language change like navigation.
**How to avoid:** Use `router.refresh()` — it re-executes Server Components on the current URL, causing next-intl to re-read the updated cookie.
**Warning signs:** Language appears to change but user is redirected to dashboard regardless of which page they were on.

### Pitfall 3: Cookie Not Set Before First Render

**What goes wrong:** Login page shows English even when user's browser is Spanish, because the cookie doesn't exist yet on first visit.
**Why it happens:** Cookie is only set when user explicitly picks a language.
**How to avoid:** In the login page, use `navigator.language` (client-side) to detect browser locale on mount and set the `locale` cookie via JavaScript before the language switcher renders. Or handle this in `i18n/request.ts` by falling back to the `Accept-Language` header.
**Warning signs:** Pre-auth language switcher ignores browser locale on first visit.

### Pitfall 4: Auth.js JWT Does Not Auto-Update After Language Change

**What goes wrong:** User changes language. Cookie updates. But `session.user.language` in JWT still shows old value until re-login.
**Why it happens:** JWT is stateless — it only updates when `update()` is called or on re-login.
**How to avoid:** Call `update({ language: newLocale })` from the LanguageSwitcher component after the DB PATCH succeeds. This triggers the Auth.js `jwt` callback with `trigger="update"` and updates the token in-place (same pattern already used for `active_tenant_id`).
**Warning signs:** `session.user.language` returns stale value after language switch; `router.refresh()` doesn't update language because the JWT callback is still reading the old value.

### Pitfall 5: next-intl v4 Breaking Change — `NextIntlClientProvider` Is Now Required

**What goes wrong:** Client Components using `useTranslations` throw errors in v4 if `NextIntlClientProvider` is not in the tree.
**Why it happens:** v4 removed the implicit provider behavior that v3 had. The requirement became explicit.
**How to avoid:** Ensure `NextIntlClientProvider` wraps the entire app in `app/layout.tsx`, NOT just the dashboard layout.
**Warning signs:** `Error: Could not find NextIntlClientProvider` in browser console.

### Pitfall 6: Template Translations Not Applied When Portal Language Changes

**What goes wrong:** User switches to Spanish but template names/descriptions still show English.
**Why it happens:** The `/api/portal/templates` endpoint returns raw DB data without locale-merging.
**How to avoid:** The templates API endpoint must accept a `?locale=es` param and merge the `translations[locale]` fields over the base English fields before returning to the client.
**Warning signs:** Template gallery shows English names after language switch.

### Pitfall 7: Session-Scoped Cookie (next-intl v4 Default)

**What goes wrong:** User picks Spanish. Closes browser. Reopens and sees English.
**Why it happens:** next-intl v4 changed the locale cookie to session-scoped by default (GDPR compliance). The cookie expires when the browser closes.
**How to avoid:** For this portal, set an explicit cookie expiry of 1 year (`max-age=31536000`) in the LanguageSwitcher when writing the `locale` cookie directly. The DB-persisted preference is the authoritative source; cookie is the fast path. `i18n/request.ts` should also read the DB value from the session token if available.
**Warning signs:** Language resets to default on every browser restart.

### Pitfall 8: `next-intl` Plugin Missing From `next.config.ts`

**What goes wrong:** `useTranslations` throws at runtime in Server Components.
**Why it happens:** Without the SWC plugin, the async context required for server-side translations is not set up.
**How to avoid:** Wrap the config with `withNextIntl` in `next.config.ts` — required step, not optional.
**Warning signs:** `Error: No request found. Please check that you've set up "next-intl" correctly.`

---

## Code Examples

Verified patterns from official sources:

### Complete `i18n/request.ts` (Without URL Routing)
```typescript
// Source: https://next-intl.dev/docs/getting-started/app-router/without-i18n-routing
import { getRequestConfig } from 'next-intl/server';
import { cookies } from 'next/headers';

const SUPPORTED_LOCALES = ['en', 'es', 'pt'] as const;
export type Locale = typeof SUPPORTED_LOCALES[number];

export function isValidLocale(l: string): l is Locale {
  return (SUPPORTED_LOCALES as readonly string[]).includes(l);
}

export const LOCALE_COOKIE = 'konstruct_locale';

export default getRequestConfig(async () => {
  const store = await cookies();
  const raw = store.get(LOCALE_COOKIE)?.value ?? 'en';
  const locale: Locale = isValidLocale(raw) ? raw : 'en';

  return {
    locale,
    messages: (await import(`../messages/${locale}.json`)).default,
  };
});
```

### `app/layout.tsx` Root Layout with Provider
```typescript
// Source: https://next-intl.dev/docs/getting-started/app-router/without-i18n-routing
import { NextIntlClientProvider } from 'next-intl';
import { getLocale, getMessages } from 'next-intl/server';
import type { Metadata } from 'next';
import { DM_Sans, JetBrains_Mono } from 'next/font/google';
import './globals.css';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const locale = await getLocale();
  const messages = await getMessages();

  return (
    <html lang={locale} className={`${dmSans.variable} ${jetbrainsMono.variable} h-full antialiased`}>
      <body className="min-h-full flex flex-col">
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}
```

### System Prompt Language Instruction
```python
# packages/shared/shared/prompts/system_prompt_builder.py
LANGUAGE_INSTRUCTION = (
    "Detect the language of each user message and respond in that same language. "
    "You support English, Spanish, and Portuguese."
)

# In build_system_prompt(), append before or after AI_TRANSPARENCY_CLAUSE:
sections.append(LANGUAGE_INSTRUCTION)
sections.append(AI_TRANSPARENCY_CLAUSE)
```

### Invitation Email With Language Parameter
```python
# packages/shared/shared/email.py
def send_invite_email(
    to_email: str,
    invitee_name: str,
    tenant_name: str,
    invite_url: str,
    language: str = "en",  # New parameter — inviter's current language
) -> None:
    ...
    subjects = {
        "en": f"You've been invited to join {tenant_name} on Konstruct",
        "es": f"Has sido invitado a unirte a {tenant_name} en Konstruct",
        "pt": f"Você foi convidado para entrar em {tenant_name} no Konstruct",
    }
    subject = subjects.get(language, subjects["en"])
    ...
```

### Migration 009 — Language Field + Template Translations
```python
# migrations/versions/009_multilanguage.py
def upgrade() -> None:
    # Add language preference to portal_users
    op.add_column('portal_users',
        sa.Column('language', sa.String(10), nullable=False, server_default='en')
    )

    # Add translations JSONB to agent_templates
    op.add_column('agent_templates',
        sa.Column('translations', sa.JSON, nullable=False, server_default='{}')
    )

    # Backfill translations for all 7 existing templates
    conn = op.get_bind()
    # ... UPDATE agent_templates SET translations = :translations WHERE id = :id
    # for each of the 7 templates with ES + PT translations
```

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| next-i18next | next-intl | 2022-2023 | next-i18next is Pages Router-centric; next-intl is the App Router standard |
| URL-prefixed locale routing (`/en/`) | Cookie/DB locale without URL prefix | Recognized pattern 2024+ | Authenticated portals don't need SEO locale URLs |
| next-intl v3 implicit provider | next-intl v4 explicit `NextIntlClientProvider` required | Feb 2026 (v4.0) | Must wrap all client components explicitly |
| next-intl session cookie | next-intl v4 session cookie (GDPR) | Feb 2026 (v4.0) | Cookie now expires with browser; must set `max-age` manually for persistence |

**Deprecated/outdated:**
- `middleware.ts` in Next.js: renamed to `proxy.ts` in Next.js 16 (already done in this codebase)
- `zodResolver` from hookform/resolvers: replaced with `standardSchemaResolver` (already done — this is relevant because Zod error messages also need i18n)

---

## Open Questions

1. **Template Translation Quality**
   - What we know: User wants templates that "feel native, not machine-translated"
   - What's unclear: Will Claude generate the translations during migration seeding, or will they be written manually?
   - Recommendation: Planner should include a task note that the Spanish and Portuguese template translations must be human-reviewed; generate initial translations with Claude then have a native speaker verify before production deploy.

2. **Zod Validation Messages**
   - What we know: Zod v4 supports custom error maps; existing forms use `standardSchemaResolver`
   - What's unclear: Zod v4's i18n integration path is not documented in the searched sources
   - Recommendation: Pass translated error strings directly in the Zod schema definitions rather than using a global error map — e.g., `z.string().email(t('validation.invalidEmail'))`. This is simpler and works with existing `standardSchemaResolver`.

3. **Session Language Sync Timing**
   - What we know: The JWT `update()` pattern works for `active_tenant_id`; same pattern applies to `language`
   - What's unclear: Whether `getLocale()` in `i18n/request.ts` should prefer the JWT session value or the cookie value when both are available
   - Recommendation: Priority order: DB/JWT value (most authoritative) → cookie → default `'en'`. Implement by reading the Auth.js session inside `getRequestConfig` and preferring `session.user.language` over cookie.

---

## Validation Architecture

### Test Framework
| Property | Value |
|----------|-------|
| Framework | pytest 8.3+ with pytest-asyncio |
| Config file | `pyproject.toml` (`[tool.pytest.ini_options]`) |
| Quick run command | `pytest tests/unit/test_system_prompt_builder.py -x` |
| Full suite command | `pytest tests/unit -x` |

### Phase Requirements → Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| I18N-03 | `build_system_prompt()` appends language instruction | unit | `pytest tests/unit/test_system_prompt_builder.py -x` | ✅ (extend existing) |
| I18N-03 | Language instruction present on all code paths (full, minimal, empty args) | unit | `pytest tests/unit/test_system_prompt_builder.py::TestLanguageInstruction -x` | ❌ Wave 0 |
| I18N-06 | `isValidLocale()` returns false for unsupported locales, true for en/es/pt | unit | `pytest tests/unit/test_i18n_utils.py -x` | ❌ Wave 0 |
| I18N-01 | Portal UI loads in Spanish when cookie is `es` | manual-only | N/A — requires browser render | — |
| I18N-02 | Language switcher PATCH updates `portal_users.language` | integration | `pytest tests/integration/test_language_preference.py -x` | ❌ Wave 0 |
| I18N-04 | Templates API returns translated fields when `?locale=es` | integration | `pytest tests/integration/test_templates_i18n.py -x` | ❌ Wave 0 |
| I18N-05 | Login form shows Spanish error on invalid credentials when locale=es | manual-only | N/A — requires browser render | — |

**Note:** I18N-01 and I18N-05 are frontend-only concerns (rendered TSX). They are verifiable by human testing in the browser and do not lend themselves to automated unit/integration tests without a full browser automation setup (Playwright), which is not in the current test infrastructure.

### Sampling Rate
- **Per task commit:** `pytest tests/unit/test_system_prompt_builder.py -x`
- **Per wave merge:** `pytest tests/unit -x`
- **Phase gate:** Full suite green before `/gsd:verify-work`

### Wave 0 Gaps
- [ ] `tests/unit/test_system_prompt_builder.py` — extend with `TestLanguageInstruction` class covering I18N-03 language instruction on all `build_system_prompt()` call paths
- [ ] `tests/integration/test_language_preference.py` — covers I18N-02 PATCH language endpoint
- [ ] `tests/integration/test_templates_i18n.py` — covers I18N-04 locale-aware templates endpoint

---

## Sources

### Primary (HIGH confidence)
- Next.js 16 official docs (local): `packages/portal/node_modules/next/dist/docs/01-app/02-guides/internationalization.md` — Next.js i18n guide, routing patterns, proxy.ts locale detection
- next-intl official docs (WebFetch): https://next-intl.dev/docs/getting-started/app-router/without-i18n-routing — complete without-routing setup
- next-intl official docs (WebFetch): https://next-intl.dev/docs/environments/server-client-components — server vs client component translation patterns
- next-intl v4 changelog (WebFetch): https://next-intl.dev/blog/next-intl-4-0 — breaking changes including mandatory `NextIntlClientProvider` and session cookie change
- GitHub (WebFetch): https://github.com/amannn/next-intl — confirmed v4.8.3 as of 2026-02-16
- next-intl without-routing cookie example (WebFetch): https://next-intl.dev/docs/usage/configuration

### Secondary (MEDIUM confidence)
- Blog guide for without-routing implementation: https://jb.desishub.com/blog/nextjs-i18n-docs — verified against official docs
- WebSearch 2026 ecosystem survey confirming next-intl as the App Router standard

### Tertiary (LOW confidence)
- Python language detection library comparison for AI agent language detection fallback (websearch only) — not required for v1 (system prompt handles detection at LLM level)

---

## Metadata

**Confidence breakdown:**
- Standard stack (next-intl v4): HIGH — confirmed via official Next.js docs listing it first + version confirmed from GitHub + docs read directly
- Architecture (without-routing pattern): HIGH — official next-intl docs page read directly via WebFetch
- next-intl v4 breaking changes: HIGH — read from official changelog
- Pitfalls: HIGH for pitfalls 1–5 (all sourced from official docs); MEDIUM for pitfalls 6–8 (derived from architecture + v4 changelog)
- Template translations approach: HIGH — standard JSONB pattern, well-established PostgreSQL convention
- AI agent language instruction: HIGH — system prompt approach is simple and confirmed effective by industry research

**Research date:** 2026-03-25
**Valid until:** 2026-06-25 (next-intl fast-moving but stable API; 90 days)
