# Arabic dialect and tone

> Make the agent sound like your team — Saudi, Gulf or Modern Standard Arabic, or English — with the right tone, bilingual fixed replies and Arabic-aware search.

Customers in Saudi Arabia and the Gulf write in dialect, switch between Arabic and English mid-sentence, and type Arabic numbers and Latin letters interchangeably. K-Agent treats language as a setting you control, not something left to chance.

## Choose the dialect

Turn on the identity block and pick a dialect:

```json
{
  "identity": {
    "enabled": true,
    "bot_name": "مساعد ندى",
    "dialect": "saudi",
    "tone": "friendly",
    "persona_notes": ""
  }
}
```

| `dialect` | What the agent is told | Typical reply to «كم سعر دهن العود؟» |
|---|---|---|
| `match` (default) | Reply in whatever language and dialect the customer wrote in; if they write Arabic, answer in the same kind of Arabic. | Follows the customer. |
| `saudi` | Reply in natural, spoken Saudi Arabic — the way a person at the branch would talk — not formal MSA. | «دهن العود الملكي عندنا بـ 450 ريال.» |
| `gulf` | Reply in natural, spoken Gulf (Khaleeji) Arabic, not formal MSA. | «دهن العود الملكي عندنا بـ 450 ريال.» |
| `msa` | Reply in Modern Standard Arabic. | «سعر دهن العود الملكي 450 ريالًا.» |
| `english` | Reply in English. | "Our Royal Oud oil is SAR 450." |

For an explicit dialect (anything but `match`), K-Agent repeats the language rule **at the very end** of the prompt, right before the customer's message, and adds that it applies no matter which language the customer or your instructions use. In practice this is what stops an English-configured agent from drifting into Arabic when your instructions are written in Arabic — and the reverse.

`identity.enabled` must be on for the dialect, tone, bot name and persona notes to take effect. Turned off, the block adds nothing to the prompt.

## Choose the tone

| `tone` | Effect |
|---|---|
| `friendly` (default) | Warm and human, in short messages — the way people actually chat. |
| `formal` | Polite and professional; respectful and to the point. |
| `brief` | As few words as possible: no pleasantries, no filler, just the answer. |

Use `persona_notes` (up to 4,000 characters) for anything more specific: "Address customers as أستاذ or أستاذة", "Never use emoji", "Mention the loyalty program when it fits".

## Instructions in Arabic or English

Write your instructions and knowledge in the language your team thinks in — Arabic, English or both. The platform's own safety rules are always given to the model in English, the language they were measured and tuned in; the `dialect` setting decides the language of the **reply**, not of the prompt. You can see every block, with its source, in the dashboard's prompt X-ray.

## Change it per request

If the agent allows it in `overrides.allowed`, an `ask` call can change the dialect or tone for one answer — useful when the same agent serves an Arabic website and an English app:

```json
{
  "input": "What are your opening hours?",
  "overrides": { "dialect": "english", "tone": "brief" }
}
```

A dialect override is applied as the final language rule even when `identity.enabled` is off.

## Fixed replies in both languages

Messages that customers read word for word are stored in **both** languages: the escalation reply, the fallback message, the handoff expiry notice, the out-of-hours message, and the widget's greeting and launcher label.

```json
{
  "fallback": {
    "message": {
      "ar": "عذرًا، واجهتنا مشكلة تقنية. أحد زملائنا سيكمل معك هنا.",
      "en": "Sorry, we hit a technical problem. A colleague will continue with you here."
    }
  }
}
```

K-Agent picks the language of the customer's latest message: when 30% or more of its letters are Arabic, the Arabic text is used; otherwise the English one. If the message has no letters, the agent's `locale.language` decides. A blank text falls back to K-Agent's built-in default for that language.

## Search that understands Arabic spelling

`search_knowledge` folds Arabic before matching, so the way a customer types never hides an answer:

| The customer types | It also matches |
|---|---|
| `اسعار` | `أسعار` |
| `مدرسه` | `مدرسة` |
| `مستشفي` | `مستشفى` |
| `العُود` (with diacritics) | `العود` |
| `٢٠٠` | `200` |
| `صندق بخور` (missing letter) | `صندوق بخور` |

See [Knowledge](/docs/en/concepts/knowledge/#arabic-aware-search) for the exact rules.

## Numbers, dates and direction

- Everything K-Agent writes for people — dashboard, widget, notices, these docs — uses **Gregorian dates and Latin digits** in both languages, with ص/م for AM/PM in Arabic.
- Arabic UIs are laid out right to left: the widget follows its `lang` attribute, then the page's `<html lang>`, then the agent's language. Code, IDs and keys always stay left to right.

## Our shared words

The dashboard, website, widget and these docs use one glossary:

| English | Arabic |
|---|---|
| AI conversation | محادثة ذكية |
| agent | وكيل |
| session | جلسة |
| end user | العميل |
| handoff | التحويل لموظف |
| Handoff Desk | مكتب التحويل |
| draft / publish / version | مسودة / نشر / إصدار |
| knowledge | المعرفة |
| tool | أداة |

## A checklist for Arabic agents

1. Turn on identity and choose `saudi`, `gulf` or `msa` — or leave `match` if your customers mix languages.
2. Write the escalation reply, fallback message and expiry notice in **both** Arabic and English.
3. Put prices, hours and addresses in knowledge, exactly as you want them said. The agent never invents facts it wasn't given.
4. Test in the dashboard with real phrasing: dialect spellings, Arabic digits, a mix of Arabic and English.
5. Read the prompt X-ray once, to see exactly what the model receives.