> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fix pronunciation with dictionaries

> Create a pronunciation dictionary of words and corrections, test each word on a voice, import or export it as a file, and turn it on for your agents.

A pronunciation dictionary tells your agents how to say specific words. You list a word and its correction, and the agent says the correction instead. Use it for brand names, product names, places and Arabic words the voice gets wrong. "Dictionaries belong to the project, so every agent can use them."

## Before you start

Owners and admins create, import and delete dictionaries by default; members can view them. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## Write a good correction

"Write the correction the way the agent should say the word." Two common Arabic cases:

| Problem | Correction | Example |
| - | - | - |
| An Arabic word is pronounced wrong | Spell it phonetically, with harakat | علم → عِلْم |
| A foreign word is spelled in Arabic | Use its original spelling | جوجل → Google |

Keep corrections short, and test each one on the voice your agent uses: "a correction isn't guaranteed to sound right on every voice", and corrections "don't always carry over between voices".

## Create a dictionary

**1. Open Dictionaries**

Go to **Voices** and set **Section** to **Dictionaries**. From an agent, you can also open **Voice dictionaries** > **Manage library**.

![The Dictionaries section of the Voices page, listing three dictionaries with their entry counts and the Create button](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/voices/dictionaries-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=c29647bb93050554073f8e242e699eee)

**2. Create it**

Click **Create**, enter a **Dictionary name** (up to 100 characters), and click **Create**.

**3. Select a voice**

Pick the voice to preview with, usually the one your agent speaks with. A voice is required to save. It is used only for previews and tests; on calls the agent's own voice says the corrections.

**4. Add entries**

Click **Add entry**. Under **Source**, type the word as the agent writes it. Under **Correction**, type how it should be said. A source can be a phrase of several words.

![The editor for the Brand and product names dictionary with the Noura voice selected, filters All, Untested, Attempted, Failed and Passed, and four entries: two untested, one marked as sounding right and one marked as not sounding right with a hint to try another spelling](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/voices/dictionary-editor-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=218a3e040304727d250d81eb72d59959)

**5. Test each entry**

Click **Preview pronunciation on the selected voice**, then mark it **Sounds right** or **Doesn't sound right**. To hear it in context, use **Preview in your own sentence**.

**6. Save**

Click **Save**. Saving is blocked while two rows have the same source word, or a row is missing its source or correction.

Your **Sounds right** and **Doesn't sound right** marks are notes for you only: "they don't change which words or corrections the agent uses. Every entry you save is applied." Filter entries by **All**, **Untested**, **Attempted**, **Passed** or **Failed** to see what is left to check.

If a correction doesn't sound right, "Try a different phonetic spelling (harakat), or use the word's original spelling, then preview again."

## Import and export entries

To add many words at once, click **Import** and upload an Excel (.xlsx) or CSV file with a "source" column and a "correction" column. **Download CSV template** and **Download Excel template** give you a file to fill in.

![The Import dictionary dialog with Download Excel template, Download CSV template and a drop area for an Excel or CSV file with source and correction columns](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/voices/dictionary-import-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=ededa65fa0f1a28d90a2c371d066be11)

Before importing, the app shows what will happen:

* Empty rows, and rows missing a source or correction, are skipped.
* If a source appears twice in the file, the last value is kept.
* A source that is already in the dictionary is updated with the new correction.

To get the entries out, click **Export** > **Export as Excel (.xlsx)** or **Export as CSV**.

## Turn a dictionary on for an agent

> [tab] Single prompt agent
>
> In the agent's settings, find **Voice dictionaries** and click **Manage**. In **Select voice dictionaries**, tick the dictionaries to use and click **Done**.
>
> ![Select voice dictionaries in the Configuration panel, with Brand and product names and Store locations ticked, Order terms not ticked, and Done](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/voices/select-voice-dictionaries-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=de66c5767c7702c53ba44c324fee1948)

> [tab] Flow agent
>
> Open **Global settings** and find **Voice dictionaries**. Choose the dictionaries to use.

Which dictionaries an agent uses is part of its version, so publish to make the change reach callers. See [Drafts and versions](https://docs.tryhamsa.com/agents/release/drafts-and-versions.md).

The entries themselves are shared. When you edit a dictionary, every agent that uses it says the new corrections from its next call, with no publish.

## How it works on a call

* The agent writes its reply, and right before it is spoken, each source word or phrase in it is replaced by its correction.
* If two of the agent's dictionaries have the same source word, only one of the corrections is used. Keep each word in one dictionary.
* Arabic diacritics are ignored when matching, so عِلْم and علم match the same entry. The correction is spoken with the diacritics you wrote.
* Only whole words match. A word with a letter attached, such as وجوجل for جوجل, is a different word: add it as its own entry if the agent says it.
* When two entries overlap, the longer phrase wins.
* Matching respects letter case. Add each spelling the agent may write, for example both "Hamsa" and "HAMSA".

- The transcript shows what the agent wrote. Only the speech changes.
- A [Change settings step](https://docs.tryhamsa.com/agents/flow/steps/change-settings.md) can switch the dictionaries for the rest of the call.

## Good to know

* A dictionary name is 1 to 100 characters.
* When you delete a dictionary, a toast offers **Undo** for about six seconds. After that the dictionary is deleted for good.

- Use a dictionary for words the voice says wrong. To change what the agent says, change its prompt instead.

## Related

> [card] [Choose a voice](https://docs.tryhamsa.com/agents/voices/choose-a-voice.md)
>
> Pick the voice your agent speaks with.

> [card] [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md)
>
> The rest of the agent's voice settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.