Localization

Localization serves guides and surveys in different languages from a single source, routing each user to the version that matches their recorded locale. Supported languages are configured per project.

Use localization when your users span multiple languages and you want a single guide or survey that adapts per locale. To deliver entirely different content per market (not just translated text), create separate guides or surveys instead.

To create localized versions of your guides and surveys, you must:

Update the SDK to record the user's locale.
Update your project settings to specify which languages to support.
Specify how each supported language behaves.
Create the translated versions of your guides and surveys.

Update the Guides and Surveys SDK to record locale

Update the SDK to record each user's locale during the Guides and Surveys SDK initialization. With an accurate user locale, the SDK serves the correct translation of your guide or survey.

Make the following change in your SDK:

const currentLocale = getLocale(); // "en" or "en-US"

// Add the plugin before calling amplitude.init()
amplitude.add(window.engagement.plugin({ locale: currentLocale }));
amplitude.init("API_KEY");

Locale code

Amplitude considers the language of a locale code for certain languages. Refer to the supported locales list below for details.

Update project settings to support multiple languages

Navigate to Project Settings > Guides and Surveys to configure localization.

On this tab, you can:

Enable or disable localization
View the default language
Define the languages available for your guides and surveys
Set the fallback behavior when a translation file is unavailable or out of date

Guides & Surveys supports ISO 639 language codes, and the following locales:

English: en-US, en-GB, en-AU, en-CA, en-IN
Spanish: es-ES, es-MX, es-AR, es-CO
French: fr-FR, fr-CA
Portuguese: pt-BR, pt-PT
Chinese: zh-CN (Simplified), zh-TW (Traditional), zh-HK (Hong Kong, Traditional)
German: de-DE, de-AT, de-CH
Arabic: ar-SA, ar-EG, ar-MA

English is the default language for all projects. Only Amplitude Support staff can change this default. To update your default language, contact Amplitude Support.

To add a supported language

In the Supported languages section, click Add language.
In the menu, search for or scroll to select the languages you need. You can select as many as you need.
Click Apply.

Configure fallback behavior

Fallback behavior controls what appears when localized content isn't available. You can configure two types of fallback:

When translation is unavailable: If a translation for a guide or survey isn't uploaded, choose whether the content appears in the default language or doesn't appear at all.
When translation is outdated: If the default content changes but the translated content doesn't reflect the change, choose whether to show the default language, show the outdated translated version, or hide the content.

When you choose not to show content, Amplitude skips the guide or survey entirely for users on an unsupported locale. No error appears and the experience doesn't fall back to the default language. The Localization section of any guide or survey's Setup page shows your project's current fallback setting.

Add localized content to a guide or survey

You can add localized versions to existing guides or surveys, or include localized content as you create new ones. Images in guide and survey content are localizable. You can upload a different image for each supported language, or use a single shared image across all locales.

To add localized content to a guide or survey

Open an existing guide or survey, or click Create Guide or Create Survey.
For an existing guide or survey, click Setup.
For a new guide or survey, create and save the default content, then click Setup.
Scroll to the Localization section.

Template language

When you create a guide or survey from a template, Amplitude generates the starting copy in your dashboard language and saves it as the guide's content. If you author in a language other than English, the source strings in your translation template file are in that language. Form factor and position labels in the builder follow your dashboard language too, but they're interface labels rather than content, so Amplitude doesn't translate them.

Translatable strings

You can localize the following parts of guides and surveys:

Translate content

You can add localized content to your guide or survey in several ways:

Use the web interface to add or edit translations. Amplitude recommends this method.
Use AI localization to translate your content automatically. Amplitude recommends this method for quick, automated translations.
Use the .xliff file to add or edit translations. Amplitude recommends this method if you integrate with a custom translation workflow.
Use the localization API to add or edit translations. Amplitude recommends this method for automated translation workflows. The API takes longer to set up, but suits larger teams or teams that support many languages.

The web interface is the preferred method for adding localized content because it maps directly to each text string.

Click the Build tab of your guide or survey.
In the upper-right of the screen, click the language toggle. The default is English.
Select the language you need.
Update the individual strings with your translated content. Amplitude associates each string with the language shown in the language toggle.

Per-locale images

Image blocks show a separate upload control for each selected language. Uploading an image while a non-default language is selected creates a locale-specific image instead of replacing the default.

Preview a translation

When you preview a localized guide or survey, the preview bar displays translation-related issues that may prevent the guide or survey from showing.

Was this helpful?