Localization lets you serve guides and surveys in different languages without creating a new guide or survey for each language. Supported languages are configured per project.

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](/docs/guides-and-surveys/sdk). With an accurate user locale, the SDK serves the correct translation of your guide or survey.

Make the following change in your SDK:

{% code-group %}
```js Amplitude SDK
const currentLocale = getLocale(); // "en" or "en-US"

amplitude.add(window.engagement.plugin({ locale: currentLocale }));
```

```js Third-party analytics
// replace with the function you need
const currentLocale = navigator.language; // for example: "en-US"

engagement.init(apiKey, { locale: currentLocale }); // for use with third-party Analytics SDKs
```
{% /code-group %}

{% callout type="note" heading="Locale code" %}
Amplitude considers the language of a locale code for certain languages. Refer to the supported locales list below for details.
{% /callout %}

## 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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) 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`

{% callout type="note" heading="" %}
English is the default language for all projects. Only Amplitude Support staff can change this default. To update your default language, contact [Amplitude Support](https://gethelp.amplitude.com).
{% /callout %}

##### To add a supported language

1. In the Supported languages section, click **Add language**.
2. In the menu, search for or scroll to select the languages you need. You can select as many as you need.
3. 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.

## 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.

##### To add localized content to a guide or survey

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

### Translatable strings

You can localize the following parts of guides and surveys:
{% accordion title="Click for more information..." %}

- Guide step title
- Guide step description
- Survey step title
- Survey step description
- Checklist title
- Checklist description
- Button text (primary and secondary)
- Checklist done button label
- Snooze label
- Survey text prompt
- Survey rating lower label
- Survey rating upper label
- Survey list required message
- Survey list "other" option label
- Survey list "other" option placeholder
- Survey list input options
- Video URL
{% /accordion %}

### 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](/docs/apis/guides-and-surveys/guides-and-surveys-api-localization) 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.

{% tabs tabs="Web interface, AI localization, XLIFF file upload" %}
{% tab name="Web interface" %}
The web interface is the preferred method for adding localized content because it maps directly to each text string.

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

{% /tab %}
{% tab name="AI localization" %}
AI localization translates your guide or survey content automatically using [Claude](https://claude.ai/login?returnTo=%2F%3F). Amplitude takes the strings from the default language and attempts to:

- Maintain the original meaning and tone.
- Make the translations natural and user-friendly.
- Preserve HTML tags, formatting, and special characters.

Amplitude can't guarantee the accuracy of AI-translated strings, so review AI-translated content manually before publishing. You can edit AI translations through the web interface.

##### To use AI localization

1. Complete the guide or survey's steps in the default language.
2. In the Localization section of the Setup tab, select one of the following:
   - **Translate All Languages**: Translate your content into all languages set in your project settings.
   - **Translate Selected Language**: Translate your content for a single language.

{% /tab %}
{% tab name="XLIFF file upload" %}
If you want to integrate with your own translation workflow, you can download an [.xliff](https://en.wikipedia.org/wiki/XLIFF) file for each language.

##### To upload an XLIFF file

1. Create the guide or survey in the default language.
2. Download the translation template. This template is a .xliff file that contains [translatable strings](#translatable-strings) from each step of your guide or survey.

{% callout type="tip" heading="Adding translations to the xliff files" %}
Guides and Surveys template files put untranslated content inside `<source>` tags in an .xliff file. Don't change the content in these tags. Add translations to the `<target>` tags. For example:
`xml
        <trans-unit id="done_label">
            <source>Finish</source>
            <target>Terminer</target>
        </trans-unit>
    `
{% /callout %}

3. Create translations to your target languages with the template file and upload a translated .xliff file for each language. If you don't upload a file for a language, Guides and Surveys follows the specified fallback setting for a missing translation. To include HTML in your guide or survey content (for example, `<br>` tags), escape the HTML in the `<target>` tag. For example:
   `xml
   <target>First line&lt;br&gt;Second line</target>
   `
4. After you upload an .xliff file, review the content by toggling through the language picker.

{% callout type="tip" heading="Update translations" %}
After you upload a translation .xliff file, you can still update localized content on the appropriate step of the guide or survey. Amplitude applies your updates to the uploaded .xliff file to keep it in sync.
{% /callout %}
{% /tab %}
{% /tabs %}

### 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.