Language configuration
Configure supported languages and the default language for a flow
Every flow version has a list of flow supported languages and a flow default language, selected when the flow is created. End users see the Player UI in their preferred language if it is in the flow supported languages; otherwise the flow default language is used.
Key terms
Player language — A language supported by the Player UI. See full list of supported languages in Create session.
Session language — The language optionally passed by your application at session creation via metadata.locale. See the metadata parameters in Create session for accepted values. When set, the Player always attempts to use it first.
Flow languages — Languages optionally configured per flow version. They define which languages a flow is available in and which is the default. Flow languages can only be selected from the available Player languages, either when creating a new flow or later via Configuration in the Flow Editor. Configuring flow languages is also required to use the Translation manager.
Two values are set per flow:
- Flow supported languages — The set of languages the flow is available in.
- Flow default language — The fallback defined in the flow's language configuration; always one of the flow supported languages.
Browser language — The language reported by the user's device or browser (via the Accept-Language header).
How the Player selects a language
The language selection logic depends on whether the flow has flow languages configured. In both cases, passing a locale that is not a Player language returns a 400 Bad Request at session creation.
Flows with flow languages configured
When a flow has flow supported languages and a flow default language configured, the Player determines the display language in the following order:
- Session language — if provided and it is in the flow supported languages. If it is not in the flow supported languages, the browser language is tried next.
- Browser language — if it is in the flow supported languages.
- Flow default language — the fallback defined in the flow's language configuration; always one of the flow supported languages.
Flows without flow languages configured
Flows without flow supported languages or a flow default language configured behave differently:
- Session language — if provided.
- Browser language — if no session language is provided and it is a Player language.
- English — the final fallback.
Configuring languages for a flow
Languages are set per flow version and are carried over when you create a new flow version from a previous flow version.
At flow creation
When creating a new flow in Studio, you are prompted to choose:
- Flow supported languages — the languages the flow is available in (at least one required).
- Flow default language — the fallback used when neither the session language nor the browser language matches a flow supported language; must be one of the flow supported languages.
After creation
You can change the flow languages at any time via the Configuration button at the top of the Flow Editor.
Drafting a new flow version
When you create a new flow version from a previous flow version, the flow supported languages and the flow default language are carried over automatically. The new draft starts with the same language configuration as its origin, which you can then modify.
Previewing a flow in the Flow Editor
In the Flow Editor, clicking Launch Session opens a modal where you can set a session language before starting a preview session.
The language selector defaults to Auto-detect, which means no session language is set. The options shown depend on the flow version's language configuration:
- Flow languages configured — the selector lists only the flow supported languages.
- Flow languages not configured — the selector lists all Player languages.