Writing scripts for Arabic TTS: tashkeel, numbers and punctuation

Arabic is one of the richest languages you can put through a text-to-speech engine, and one of the easiest to get subtly wrong. Written Arabic usually leaves out short vowels, the same digits can be read in several ways, and most scripts mix in English names. A voice model can only guess where the text is ambiguous. This guide shows how to remove those guesses before you press generate.

Why Arabic scripts need preparation

Readers of Arabic resolve ambiguity from context without thinking about it. A speech model does the same, but it has less context and no way to ask you what you meant. The classic example is «علم», which can be ʿilm (knowledge), ʿalam (flag) or ʿalima (he knew). Most of the time the sentence makes the reading obvious. When it does not, the model picks the most likely option, and that is where mispronunciations come from.

The good news: a few habits fix almost all of them.

Add tashkeel where it changes the meaning

You do not need to vowel an entire script. Fully vowelled text is slower to write, harder to proofread and rarely sounds better. Add diacritics only where they remove real ambiguity:

• Names of people and places, especially less common ones: «عُمَر» and «عَمْرو», «مَعْن», «السِّيب».
• Words whose meaning changes with the vowels: «عِلْم» / «عَلَم», «قَدَّمَ» / «قَدِمَ».
• Passive verbs, which look identical to active ones: «كُتِبَ» (was written) versus «كَتَبَ» (wrote).
• Classical vocabulary, verse and Quranic quotations, where the expected pronunciation is precise.

In Vocla, diacritics are never counted toward your credits, so there is no cost to adding them. If you are unsure which words are ambiguous, click Add tashkeel in the editor to vowel the whole script or a selection and review every change before you accept it, or turn on Auto-tashkeel to vowel the script each time you generate. For a single word, the word inspector shows its possible readings, and names, brands and acronyms belong in your pronunciation dictionary. See Tashkeel & pronunciation for the full tour.

Write numbers the way you want them spoken

Numbers are the most common source of surprises. The same digits can be a price, a year, a phone number or a quantity, and Arabic adds gender and case agreement on top.

Practical rules:

• Spell out anything where agreement or reading matters: quantities of counted nouns, ordinals, years in formal narration.
• Split phone numbers and codes into short groups separated by commas so they are read digit by digit.
• Keep one date format throughout a script. Mixing «٢٠٢٦/٩/١٨» with «18 سبتمبر» makes the narration sound inconsistent.
• Western or Arabic-Indic digits both work, but do not mix them in the same number.

Currencies, units and abbreviations

Write currencies the way your audience says them. In a Saudi ad, «١٢٩ ريال» may be better written as «مية وتسعة وعشرين ريال» if you want the colloquial form; in MSA narration, «مئة وتسعة وعشرون ريالًا». Symbols such as «ر.س», «$» and «كم/س» are often read literally or skipped, so replace them with words.

Abbreviations deserve the same treatment. «د.» could be «دكتور» or a unit; «م» could be «متر» or «ميلادي». Expand them unless the abbreviation itself is what people say out loud.

Mixing Arabic and English

Code-switching is normal, especially in the Gulf: «حمّل التطبيق من App Store اليوم». Keep English brand and product names in Latin letters rather than transliterating them into Arabic script; the voice keeps them intact. Two things help:

• Avoid putting a long English sentence inside an Arabic paragraph. If a whole sentence is English, generate it separately with an English voice.
• For acronyms, decide how they should sound. «AI» is usually read as letters; if you want «الذكاء الاصطناعي», write that instead.

Punctuation is your pacing tool

Speech models use punctuation as timing cues:

• A comma creates a short pause. Use it to separate list items and clauses.
• A full stop creates a longer pause and a falling tone.
• A question mark changes the intonation, so do not leave it out of real questions.
• A new paragraph gives the narrator room to breathe between ideas.

Long Arabic sentences joined with «و» are common in writing but tiring to listen to. Break them into two or three sentences. If a passage still feels rushed after that, lower the speed slider slightly instead of rewriting it again.

Test a paragraph before generating everything

Before generating a full chapter or course, generate one representative paragraph that contains your trickiest names, numbers and terms. Listen for three things: names, numbers and the rhythm of long sentences. Fix the script, not the audio, then save the voice and settings as a preset so the rest of the project sounds the same.

A quick checklist

1. Names, places and ambiguous words have tashkeel.
2. Numbers, dates and prices are written the way they should sound.
3. Symbols and abbreviations are replaced with words.
4. English names are in Latin letters; long English sentences are generated separately.
5. Long sentences are split and questions keep their question marks.
6. One test paragraph sounds right before you generate the rest.

Ready to try it? Paste a paragraph into Vocla's text to speech and compare two or three voices from the voice library. The free plan includes 10,000 credits every month.