A Language override pairs a language or regional locale with its own text-to-speech voice and settings. The conversation’s {locale} variable chooses which override applies; the primary voice covers conversations without a match.
For example, one agent can use a primary voice for English, a French voice for fr, and a different French Canadian voice for fr-CA.
Before you begin
Open the project you want to configure. In Agent → Behaviour → Voice output, you need access to the Voices editor and Language overrides controls described below.
Choose voices and synthesis models that support the languages you plan to use. An override changes the speaking voice. Configure the language of the agent’s replies in its Global prompt; review speech recognition separately under Voice input.
Configure Language overrides
Choose the primary voice
Under Voice output → Voice, click the current voice to open the Voices editor. Select the primary voice in the left column, choose a voice from the library, and review its model and settings on the right.
The primary voice handles every conversation whose {locale} has no matching override. Choose one that supports the languages you expect to reach this fallback.
Add a language override
Return to Behaviour → Voice output and click Add language override. Search for a language, such as French (fr), or a regional locale, such as French (Canada) (fr-CA). Selecting it opens the Voices editor on the new override.
Use a language-wide override for all regions that should share a voice. Add a regional override when that region needs a different voice or accent.
Choose the override’s voice and model
With the override selected in the left column, choose its voice from the library. Review the model and available voice settings in the right column. These settings belong to this override, so check them for each language you add.
Use the play control to preview a voice. If a warning icon appears beside an override, hover over it to read the reason and choose a voice and model that support the selected language. A sample helps you assess the voice; test an actual agent reply in the target language before release.
Set the conversation’s locale
Use a language tag such as fr, fr-CA or en-US as the value of the built-in locale variable. The channel supplies its initial value as follows:
Phone-number inference is a starting preference, rather than detection of the language someone is speaking. If neither number identifies a country, no inferred locale is supplied. A browser with no usable language supplies no locale either.
To honor a customer’s explicit language choice, update locale before generating the next spoken reply. A Set step can assign the value in a Workflow. Voice selection reads the conversation variable when resolving speech; changing the variable does not itself translate the reply or change the Voice input settings.
Understand voice matching
Voiceflow checks the overrides in this order:
- Exact locale:
fr-CAuses thefr-CAoverride when one exists. - Language: if there is no exact override,
fr-CAcan use thefroverride. - Primary voice: if neither matches, or
localeis missing or unusable, the primary voice applies.
A language-only value such as fr does not select a regional override such as fr-FR. Use a language-wide override when you want to cover users whose region is unknown. Reordering rows does not replace the exact-locale-first matching rule.
French voices with a Canadian override
Compare exact, language-wide and primary-voice matches in one setup.
Assume the primary voice is your usual English voice. Add a French override (fr) and a French (Canada) override (fr-CA), each with a voice and model that support its intended speech.
If you remove the fr override, fr-FR falls back to the primary voice. The remaining fr-CA override only matches that regional locale. These are the expected selections for this configuration; verify the voices in your agent.
Language override best practices
Choose useful language coverage and make regional differences intentional.
- Start with a language-wide voice. A
froverride coversfrand regional French locales that do not have their own override. - Add regional voices for a reason. Use
fr-CAwhen Canadian French should sound different; the region in the tag does not change a chosen voice’s accent automatically. - Check the primary voice too. Unmatched and missing locales reach it, so include that path in testing.
- Honor a stated preference. A browser preference or phone number can differ from the customer’s preferred language. Let the conversation update
localewhen needed.
Test the selected voices
Run the agent with the overrides configured. For a controlled check, use a Set step to assign locale before the spoken reply, then confirm the stored locale value before the reply.
Check an exact regional match, a language fallback and a locale with no override. Listen to a complete reply in each intended language. Confirm both the voice selection and the language of the response; a voice’s preview sample alone does not test the conversation.
Reload the editor and confirm the configured overrides remain present. Before routing customers to the change, publish the Environment and repeat the checks in the channel they will use. Start a new widget session or phone call when checking the channel’s initial locale.
The primary voice still plays
Check the runtime locale, matching scope and published configuration.
- Inspect the conversation’s
localevalue before the spoken reply. For an API conversation, confirm your integration actually supplies it. - Compare that value with the configured language tags. A
fr-FRoverride does not coverfr,fr-CAor every other French locale. - Confirm the override is still present after reloading the editor, and that the channel is using the Environment and published version you updated.
The voice changes but the reply uses another language
Review response instructions and speech recognition alongside the voice.
The override selects text-to-speech settings. Review the Global prompt and any applicable Instructions or Playbook to ensure the agent generates replies in the intended language. For voice conversations, also review the speech-recognition provider, model and language under Voice input.
Remove a language override
Open the Voices editor, hover over the override in the left column, open its … menu and choose Remove override.
The next matching voice is then used: removing a regional override can expose a language-wide override; removing the last applicable override leaves the primary voice. Test that fallback and publish the change before expecting it in a published channel.