Languages & Localization

FaceSign supports 13 languages out of the box. The avatar speaks the resolved language and the wrapper UI adapts. You author prompts in English; the runtime translates the avatar's speech into the resolved session language.

Supported languages

How language resolution works

The session picks the spoken language and the wrapper UI language from the end user's navigator.language, normalized against the session's langs whitelist:

• langs specified: only those languages are allowed. If the browser language matches one, that language is used. Otherwise defaultLang is used.
• langs omitted: every language in the catalog is allowed. The browser language picks, falling back to defaultLang (default: en).

BCP-47 normalization

FaceSign normalizes navigator.language before matching. A few examples:

Author prompts and outcome conditions in English regardless of which languages your deployment supports — the runtime translates the avatar's speech into the resolved session language. Mixing authoring languages across nodes makes the avatar flip languages mid-flow. See Conversation Rules for the full rule.

Setting up a multilingual session

const { session, clientSecret } = await client.session.create({
  flow,
  avatarId,
  langs: ['en', 'it', 'de'],   // whitelist: the avatar speaks any of these
  defaultLang: 'en',            // fallback when browser lang isn't in langs
})

Omit langs to allow every catalog language. The exported Next.js app detects the user's browser language automatically and forwards it to the session — no extra code required beyond langs and optionally defaultLang.

Prompt style: Say: vs descriptive

This is the most important decision for multilingual flows. Both styles are written in English and both get translated into the session language at runtime; the difference is whether the LLM rephrases freely or sticks close to the source wording.

// The LLM generates fresh sentences in the resolved session language
prompt: "Warmly greet the user and tell them their transfer has been flagged for PSD3 verification. Ask if they're ready."

// Say: keeps the translation close to the source sentence
prompt: "Say: Hi! Your transfer's been flagged for verification. Ready?"

Amount and currency formatting

Currency formatting differs by locale. If you bake amounts into your UI strings, match the user's locale:

For numeric data, prefer Intl.NumberFormat at render time over hard-coded strings.

Adding your own UI translations

The exported app contains exactly the uiStrings your AI assistant generated at export time — there are no built-in defaults. Add or change scenario copy (product name, merchant names, your own product voice) by editing the UI strings in the exported app. Keep the key set identical across every language block. Missing keys fall back to English at runtime.

Testing without changing your browser language

Exported apps honor a ?lang=XX query parameter that overrides both the wrapper UI and the avatar's spoken language. Append it to any demo URL:

https://your-demo.vercel.app/?lang=it
https://your-demo.vercel.app/?lang=de

This makes it easy to verify multilingual behavior without reconfiguring your browser's language preferences.

Multilingual deployment checklist

• Conversation prompts are descriptive, not Say: (required for translation)
• langs whitelist set on session.create
• defaultLang set on session.create
• UI strings cover every language in langs
• Currency, date, and number formats are locale-appropriate
• Tested in each target language with the browser's primary language set accordingly, or via ?lang=XX

Next steps