Chatbot Multilingual

Chatbot Multilingual Architecture (Portfolio-Specific)

When to invoke

• Touching src/app/api/chat/route.ts.
• Touching src/components/chat/chat-widget.tsx locale-handling.
• Touching src/content/chatbot-context*.md.
• Adding or reviewing a new locale's chatbot behavior.
• Debugging reports like "the chatbot replied in English when I asked in Arabic" or "the tone feels wrong in Spanish."

Architecture in one diagram

ChatWidget (client)
  │  locale from useLocale()
  │  messages from useState
  ▼
POST /api/chat
  body: { messages, locale }  ← locale is NEW (was missing)
  │
  ▼
route.ts
  ├─ validateLocale(locale) → fallback to 'en' if missing/invalid
  ├─ loadLocaleContext(locale) → reads src/content/chatbot-context.{locale}.md (fallback EN)
  ├─ buildSystemPrompt(locale, context) → locale-routed preamble + persona + context
  ├─ streamText(model, systemPrompt, messages) → model response
  ▼
streamed response back to client

System prompt structure per locale

Every locale gets the same five-section system prompt, with the content per section varying by locale.

Section 1 — Persona (uniform brand voice, locale-specific realization)

Example for AR:

أنت مساعد رئبال الشخصي. نبرتك: عصرية، مباشرة، ودودة، لكن مهنية ومتمكنة. تتحدث بالعربية الفصحى الحديثة بمفردات الأعمال الخليجية. لا تستخدم اللهجات. لا تستخدم الفصحى الكلاسيكية الأدبية.

Example for ES:

Eres el asistente personal de Reebal. Tu tono es moderno, directo, amigable, pero profesional y competente. Hablas en español de España, con calidez andaluza en el fraseo cuando encaja. Usas "tú", nunca "usted" (salvo que el usuario lo use primero).

Example for DE:

Du bist Reebals persönlicher Assistent. Dein Ton ist modern, direkt, freundlich, aber professionell und kompetent. Du sprichst Deutsch, Du-Form mit großem D (Du, Dir, Dich). Keine Siezen-Form, es sei denn der Nutzer siezt Dich zuerst.

Section 2 — Grounding rules (uniform content, translated)

Respond only based on the provided context about Reebal. If a question is not covered by the context, say so clearly and suggest the visitor contact Reebal directly. Do not fabricate specifics.

Section 3 — Language handling

Respond in the same language the user wrote in. If the user mixes two languages in one message, respond primarily in [current locale] and briefly acknowledge the other-language phrase. Do not translate the user's message back to them unless they ask.

Section 4 — Context (from the locale-specific context file)

<context>
{{ contents of src/content/chatbot-context.{locale}.md }}
</context>

Section 5 — Scope guard

Only answer questions about Reebal (background, projects, skills, availability, relocation, contact). For general programming questions, AI industry opinions, or unrelated topics, gently redirect to Reebal's actual areas.

The locale parameter — wiring it through

Frontend (ChatWidget)

// src/components/chat/chat-widget.tsx
import { useLocale } from 'next-intl';

const locale = useLocale();

// In the POST body:
body: JSON.stringify({ messages: sanitized, locale }),

API (route.ts)

// src/app/api/chat/route.ts
const { messages, locale } = await req.json();
const validLocale = ['en', 'de', 'es', 'ar'].includes(locale) ? locale : 'en';
const context = await loadLocaleContext(validLocale);
const systemPrompt = buildSystemPrompt(validLocale, context);

loadLocaleContext

async function loadLocaleContext(locale: string): Promise<string> {
  const primary = path.join(process.cwd(), 'src/content', `chatbot-context.${locale}.md`);
  const fallback = path.join(process.cwd(), 'src/content', 'chatbot-context.md');
  try {
    return await fs.promises.readFile(primary, 'utf-8');
  } catch {
    return await fs.promises.readFile(fallback, 'utf-8');
  }
}

Per-locale context files

Structure:

• src/content/chatbot-context.md — EN (source of truth for content; always exists).
• src/content/chatbot-context.de.md — DE transcreation.
• src/content/chatbot-context.es.md — ES transcreation.
• src/content/chatbot-context.ar.md — AR transcreation.

Rules for the translated context files:

1. Content structure (headings, section order) matches EN exactly.
2. Locked glossary terms (brand, tech, job titles) render per glossary-brandbook.
3. Factual claims (years, metrics, project counts) match EN exactly.
4. Narrative paragraphs (bio, strengths) go through deep transcreation per tone-routing About-row rules.
5. Each file has a <!-- last-synced: YYYY-MM-DD from chatbot-context.md --> HTML comment at the top to track drift.

Scope guard behavior

If the user asks something out-of-scope, the bot's response (in the user's language) should:

1. Acknowledge the question briefly.
2. Say that its scope is only Reebal's profile.
3. Redirect: "For that topic, I'd suggest [general resource / talking to Reebal directly]."

Example in Arabic:

سؤال جيد، لكن مجالي محدود بمعلومات رئبال (خلفيته، مشاريعه، مهاراته). بالنسبة لهذا الموضوع، الأفضل أن تسأل رئبال مباشرة أو تبحث في مصادر مختصة.

Anti-patterns

• Don't send a single EN system prompt with an instruction "respond in the user's language." The model will respond in the right language but with EN-register semantics — which is the current failure mode.
• Don't use gpt-4o-mini as the runtime model and expect it to do HIGH-QUALITY transcreation — it's fine for mid-register conversation with a well-built system prompt, but it can't compensate for a prompt that itself ignores locale.
• Don't leak internal routing decisions into the user-facing response ("Since you're in locale 'ar', I'll respond in Arabic" — never say this).
• Don't let the context file drift from the EN source. If you update the EN context, run a drift check against all locale copies and regenerate (or at minimum flag) the outdated ones.

Integration

This skill pairs with:

• tone-routing skill — the Chatbot row defines the per-locale register.
• glossary-brandbook skill — enforces locked terms across context files.
• transcreation-audit skill — audit the context files after regeneration.

Testing

After any change to locale routing or system prompts:

1. Manual: open each of /en, /de, /es, /ar in the browser, ask 3 sample questions (simple factual, nuanced opinion, out-of-scope). Verify language, register, scope guard behavior.
2. For AR: additionally verify RTL rendering of markdown lists and code blocks in the streaming response.
3. Log + inspect the first few system messages at runtime to confirm the per-locale prompt structure is being built correctly.