usertour

This release makes localization a first-class capability: translate flows, checklists, launchers, banners, announcements and resource centers into any number of languages, let AI fill in the blanks, and deliver each user the language matching their locale_code attribute — with untranslated text always falling back to the source, so a half-finished translation never breaks content. Translations are versioned with the content and ship through the normal publish flow.

What's Changed

🌍 A translation editor for every content type

Define your languages once under Settings → Localization, then every content gets a Localization tab: pick a language and translate side by side — source on the left, translation on the right, grouped the way the content is structured (per flow step, per checklist section, and so on). Rich text keeps its formatting automatically, red and yellow markers track what's untranslated and what's outdated, an Only untranslated filter hides finished work, and everything autosaves. Resource-center content lists get translatable display names, so entries no longer leak the internal content name to end users. See the Localization guide for the full tour.

🤖 AI machine translation

One click on AI translate machine-translates everything that's still untranslated — in batches, with live progress, resumable if a batch fails. Each row also gets a magic-wand button for translating just that text. Machine translation fills blanks only: it never overwrites a translation a human wrote or edited. On Usertour Cloud it ships with every paid plan; self-hosted instances bring their own provider — Anthropic, any OpenAI-compatible gateway (OpenAI, OpenRouter, Azure, local gateways), or AWS Bedrock, configured through AI_* environment variables.

For agencies and external translators, Export CSV / Import CSV round-trips the whole translation set — blank cells keep existing translations, stale rows are skipped safely.

🚚 Delivery keyed on the user's locale

Set locale_code when you identify the user and Usertour picks the matching enabled translation — exact code first, then the primary language (fr-CA falls back to fr). The locale is never auto-detected from the browser: the right language for your product is the one your app renders in, and only your app knows that. Switching locale_code mid-session re-delivers live content in the new language on the spot. The widgets' built-in interface text — checklist prompts, survey buttons, screen-reader labels, dates — follows the same signal and ships in ten languages.

🔁 Versioned, publish-gated, preview-ready

Translations belong to the content version: enable a language when it's ready, publish to ship it, and forks or restores carry every translation along. Editing translations of a live version quietly continues on a draft — merely viewing translations never creates one. A Preview button renders any language with your working translations applied, no publish needed, and source-copy edits flag the affected rows for review so translations never silently drift.

🐛 Fixes

• Widgets now apply mid-session updates fully. A session update refreshed only part of the widget state, so changes like a plan's branding flag — and now the interface language — didn't take effect until reload.
• Checklists re-deliver when their delivered content changes. The change detector compared only task lists, so updates to the launcher button or checklist body were dropped as "no change".
• Viewers see announcement content read-only instead of an editable-looking editor, and the announcement list's guide link now points at the announcements guide.
• Settings row-action icons align on a shared icon box across all settings tables.

🛠️ Under the hood

Localization is built as a structural-merge pipeline with one delivery gate:

• Translations live in VersionOnLocalization rows — a structural clone of the source per (version, locale), where empty string means untranslated. Delivery merges structurally: the source tree owns structure and behavior, the translation donates non-empty text. Rows are keyed by step cvid, so forks and restores copy them verbatim with zero remapping.
• Locale resolution is a pure function of the locale_code user attribute (seeded and backfilled as a default attribute), shared by content delivery, widget chrome, and the delivered-locale stamp on analytics events.
• Machine translation is served by a new instance-level ai module (Vercel AI SDK; Anthropic / OpenAI-compatible / Bedrock with a three-tier AWS credential chain). Structured outputs are enforced end to end, and responses that split one translation across entries are dropped for retry instead of saving fragments.
• The translation editor saves through read-write-symmetric payload builders: a session may only overwrite what it could read, so drifted or unreadable fragments of the stored row survive every save. Published versions fork lazily on the first actual write, and the editor pins its version so its own fork never remounts it mid-edit.

Full Changelog: https://github.com/usertour/usertour/compare/v0.8.7...v0.8.8