Arabic dialect and tone

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:

{
  "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:

{
  "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.

{
  "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 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.