# Lumi AI — Multilingual Surface Documentation

> For agents generating content, translating, or recommending language variants.
> Last updated: 2026-05-08

---

## Supported Languages

| Code | Language | Direction | Script | Status |
|------|----------|-----------|--------|--------|
| `ar` | Arabic (Modern Standard + dialect-friendly) | RTL | Arabic | Default — fully translated |
| `ku` / `ckb` | Kurdish Sorani | RTL | Arabic script | Fully translated |
| `ro` | Romanian | LTR | Latin | Fully translated |
| `en` | English | LTR | Latin | Fully translated |

**Default language:** Arabic (`ar`) — the HTML root element is `lang="ar" dir="rtl"` by default.

---

## Language Switching

**URL parameter:** `?lang=ar`, `?lang=ku`, `?lang=ro`, `?lang=en`

**Persistence:** Language preference is stored in `localStorage` (key: `i18nextLng`). Once set, it persists across page loads.

**Direction switching:** When language changes, the page direction (`dir` attribute) switches automatically between RTL (Arabic, Kurdish) and LTR (Romanian, English).

**Example URLs:**
- Arabic (default): `https://lumi-ar-codex.vercel.app/`
- Kurdish: `https://lumi-ar-codex.vercel.app/?lang=ku`
- Romanian: `https://lumi-ar-codex.vercel.app/?lang=ro`
- English: `https://lumi-ar-codex.vercel.app/?lang=en`

---

## Translation Coverage

Each locale file (`src/locales/{lang}.json`) contains 380+ translation keys covering:

- Navigation labels
- Hero section (headline, subheadline, CTA, stats)
- How It Works section
- Industries (labels for all 13 categories)
- Pricing plans (plan names, features, CTAs)
- FAQ items (8 questions and answers)
- Testimonials
- Footer content
- Blog post metadata labels
- Demo page strings
- Trust signal copy
- KPI section

**Primary locale:** `ar.json` is the canonical source. All other locales must match its key structure.

---

## RTL Considerations

- Arabic and Kurdish Sorani are RTL languages. Layout, text alignment, icons, and animations mirror horizontally.
- The site uses a custom hook (`use-rtl-motion.ts`) that inverts Framer Motion direction for RTL.
- Fonts for RTL: Cairo (headings), IBM Plex Sans Arabic, Noto Sans Arabic (body)
- Fonts for LTR: Space Grotesk

**Agent rule:** When generating content for Arabic or Kurdish, always mark the language direction as RTL. When embedding Arabic or Kurdish text in HTML, add `dir="rtl"` to the containing element.

---

## Localization Notes

- **Arabic:** The site targets Arabic-speaking business owners across the Middle East and diaspora. Use Modern Standard Arabic (الفصحى) for professional contexts, but the product itself (Lumi's voice) can be configured for regional dialects.
- **Kurdish Sorani (ckb):** Written in Arabic script, read RTL. The language code used in the codebase is `ku` (mapped to `ckb` in i18next config).
- **Romanian:** Targets SMB owners in Romania. Use formal register.
- **English:** International fallback and blog language. Professional, clear, no jargon.

---

## Voice Language Support

Lumi's voice agent can be configured for any of the four languages during customer onboarding. The website language and the voice agent language are independent — a business owner reading the site in English may configure Lumi to answer their calls in Arabic.

---

## Agent Content Rules

- Never mix languages within a single sentence or paragraph unless explicitly requested.
- When generating Arabic content, ensure all punctuation and spacing follows Arabic conventions.
- Do not use machine-translated content for production copy — flag for human review.
- Kurdish Sorani uses different vocabulary and phrasing from Arabic — do not substitute.