Before you start
Owners and admins create, save and delete dictionaries by default. Members can open and test them. See Roles and permissions.Write a good correction
“Write the correction the way the voice should say the word.” Two common Arabic cases:
Keep corrections short, and test each one on the voice you will use: “a correction isn’t guaranteed to sound right on every voice”, and “Corrections don’t always carry over between voices.” Test again after you switch voices.
Create a dictionary
1
Open Dictionaries
In Voices library, switch the section to Dictionaries. The list shows each dictionary’s Name, Entries and Updated at, with Search dictionaries… above it.



2
Create it
Click Create, enter a Dictionary name (up to 100 characters), and click Create. The new dictionary opens.



3
Select a voice
Click Select voice and pick the voice to test with, usually the one you will generate with. A voice is required to save. It is only used for previews: it doesn’t change which voice speaks your scripts.



4
Add entries
Click Add entry. Under Source, type the word as it appears in your text. Under Correction, type how it should be said. A source can be a phrase of several words.



5
Test each entry
Click Preview pronunciation on the selected voice on the row, then mark it Sounds right or Doesn’t sound right. To hear the word in context, use Preview with your own sentence, type a sentence under Text to test and click Test.



6
Save
While you have unsaved changes, a bar at the bottom counts them. Click Save in the bar, or press Cmd+S (Ctrl+S on Windows). “Dictionary saved successfully”. Discard drops the changes. If two rows have the same word, Save stays off: “Repeated words. Keep one row per word to save.”


- no voice is selected (“Please select a voice before saving”),
- two rows have the same source word, whatever the letter case (“Keep only one row per word.”), or
- a row has a source without a correction, or a correction without a source.
Track what you tested
Each entry has a status for the selected voice: Untested, Attempted (previewed but not marked), Passed (Sounds right) or Failed (Doesn’t sound right). Filter by status to see what is left to check, or search the entries. The marks are notes for you: “They don’t change which words or corrections are used. Every entry you save is applied.” Changing an entry’s correction resets its mark. Marks are saved with Save. If a correction doesn’t sound right: “Try a different phonetic spelling (harakat), or use the word’s original spelling, then preview again.”Import entries from a file
1
Open Import
In the dictionary, click Import. The Import dictionary dialog opens.
2
Get the template (optional)
If you don’t have a file yet, click Download Excel template or Download CSV template. The template has a 

source column and a correction column, with two example rows. Fill it in with one word or phrase per row and keep the header row. A file of your own works too, as long as it has those two columns.

3
Upload it
Drop the file in the dialog or click to choose it. It takes an Excel (.xlsx) or CSV file with
source and correction columns. The dialog reads it and shows what will happen.4
Import and save
Click Import {n} entries. The entries are added to the editor. Click Save to keep them.


What is imported, updated or skipped
File rules:
- Only .xlsx and .csv files. Older .xls files aren’t read.
- In Excel, only the first sheet is read.
- The first row that isn’t empty is the header. It must have a
sourcecolumn (orword) and acorrectioncolumn (orreplacement), in any letter case. Other columns are ignored. - If the header doesn’t match: “This file doesn’t match the template, so nothing can be imported.” The dialog lists the columns it found.
Export a dictionary
Click Export > Export as Excel (.xlsx) or Export as CSV. The file is named after the dictionary and has the samesource and correction columns as the template, so you can edit it and import it again. Rows missing a source or a correction aren’t exported.


Where dictionaries apply
Voice overs don’t use dictionaries.
How a dictionary changes the audio
- Right before the speech is made, each source word or phrase in your script is replaced by its correction. Your saved script keeps the words you wrote; only the audio changes.
- Only whole words and phrases are replaced. An entry for “AI” doesn’t change “AIR”, and an entry for جوجل doesn’t change وجوجل. Add attached forms as their own entries.
- Arabic harakat are ignored when matching: an entry for علم also changes عِلْم in your script. If an entry with the exact harakat exists, it is used first.
- Letter case must match. Add each spelling your text uses, for example both “Hamsa” and “HAMSA”.
- When entries overlap, the longest one is used. An entry for “Hamsa Media” wins over one for “Hamsa” in that phrase. A correction is never changed again by another entry.
- If two dictionaries you turned on have the same source word, only one of the corrections is used. Keep each word in one dictionary.
Delete a dictionary
In the list, open the row’s menu and click Delete, then confirm. The dictionary leaves the list at once, and a message says “Deleted Brand names” with Undo. You have 6 seconds to click Undo and get it back; after that it’s gone for good. See Undo a delete.

Good to know
- A dictionary name is 1 to 100 characters.
- Copy ID in the row menu copies the dictionary’s ID, for the API.
- Use a dictionary for words a voice says wrong. To change the words themselves, edit your script.
Related
Generate speech
Turn dictionaries on for a script.
Voices library
Find the voice to test your corrections on.
Dictionaries in Hamsa Agents
Use the same dictionaries on calls.