All posts

Product tours in several languages: how to localize your onboarding

If your app speaks German, a tour in English is the first thing a German user sees that does not. Here is how to show each user onboarding in their own language.

5 min read
Isometric illustration of three stacked tooltip cards, each with a small round language tag in a different shade of blue

Teams translate their app, their emails and their help centre, and then ship the onboarding in English. For a new user in Lyon or Leipzig, the very first guided moment in the product is the one that is not in their language.

Localizing a tour is less work than localizing an app. There are only a few dozen sentences. The parts that take thought are deciding which language a visitor gets and keeping the versions in step with each other.

Decide which languages to support

Follow your app. If the interface exists in five languages, the onboarding should too; a tour in another language than the buttons it points at is confusing, because the step text names labels the user cannot see.

If your app is only in English, translating the tour alone rarely pays off. Start with the languages your interface already supports and add one only when the app gets it.

How Stepsome knows the visitor’s language

Your app already knows which language it is showing. Stepsome reads it from the page:

  • the lang of the page’s <html> tag, for example <html lang="de">,
  • a language prefix in the address, such as /de/,
  • ?lang=de in the address.

A version shows when any of these matches its language. If none of them is there, Stepsome falls back to the language of the visitor’s browser. A short code also matches its regional variants: de matches de-CH and de-AT.

Your app can also say it outright with Stepsome.identify({ lang: 'de' }). When it does, only that language counts and the page is not looked at.

That last option is the most reliable. A user’s language setting in your app is a choice they made; their browser language is a guess. If your app stores a language per user, pass it along in the same identify call you may already use for plan or role:

Stepsome.identify('user_42', { plan: 'pro', lang: 'nl' });

If your app sets the lang attribute correctly on every page, which it should for accessibility and search anyway, you need no code at all.

One version per language

In Stepsome, a localized tour is a copy of the original with its own text and its own language rule:

  1. Build and test the tour in one language first. Get the steps and the order right before you translate anything.
  2. In the dashboard, Duplicate it. Open the copy in the editor and translate the text of each step.
  3. In each copy, fill in Language under Audience, for example de, or de, fr for a version that serves both.
  4. Set the original’s Language too, for example en. A tour with an empty Language field shows in every language, so without this a German user would get both.

Copies keep the selectors, page rules, schedule and theme of the original, so only the words change. Name them clearly in the dashboard, for example “Welcome tour (DE)”, so you can tell them apart in the list and in analytics.

Translate for the screen, not the dictionary

  • Use the labels in your translated interface. If the German button says “Neues Projekt”, the tooltip says “Neues Projekt”, whatever a translation tool suggests. This is the most common mistake in localized tours, and the most confusing one.
  • Leave room. German and French text often runs a good deal longer than English. A tooltip that fits on two lines in English may need three. With Fit to text on, short text gets a narrow tip and longer text wraps at the width you set, so check the longest language in preview.
  • Match the form of address. If your German app says “Sie”, the tour does not say “du”. Same for “vous” and “tu” in French.
  • Translate the buttons and alt text too. “Next” and “Got it” are easy to forget when the body text is done.

The AI copywriter can help with a first pass: duplicate the tour, paste in rough translations, and use Polish all step texts to smooth them out with your own Anthropic or OpenAI key. Have a native speaker read the result before you publish it.

Announcements and checklists work the same way

Everything that shows text has the same Language field: tooltips, highlights, popups, banners, checklists and badges. A launch banner in three languages is three banners, each with its own Language. Combine it with a schedule and all three end on the same day.

For a checklist, keep the user traits that tick items off identical across copies. Then a user who switches language mid-way sees the same items ticked in the new version.

Test each language before it goes live

  1. Switch your app to the language, the way a user would.
  2. Preview the tour and check that only the German version starts. If two versions show up, the page carries two languages, for example <html lang="en"> on a /de/ address; fix the lang attribute or pass the language with identify.
  3. Click through every step. Look for text that does not match the screen, tooltips that are too wide or too tall, and buttons still in English.
  4. Repeat for each language, then download the site file and deploy.

Language rules are part of Pro, together with audiences and schedules. See pricing.

Keep the versions in step

The cost of localization is not the first translation. It is the second change, when the original tour gets a new step and the copies do not. Two habits keep that under control:

  • Change the original first, then copy the change. Make one language the source and treat the others as translations of it.
  • Compare drop-off per language. If the German tour loses far more people at step three than the English one, the translation or the screen is likely different there. How to measure user onboarding explains how to read that per step.

And if a step breaks in one language only, it is often because a selector matches on text that differs between languages. Why product tours break after a deploy explains how to make steps independent of the label.