> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embeddables.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Translations in Embeddables

> Add and edit multiple languages for your Embeddable content in the Builder

**Translations** let you offer your Embeddable in multiple languages. You configure which languages are available, then edit the content for each language in the Builder. End users see the language that matches their choice (for example via User Data or URL params).

## How translations work in the Builder

Every Embeddable has a **default language** (English). You can add more languages at the Embeddable level. Once you have more than one language:

* A **content language** dropdown appears in the Builder top bar when you're in editing mode.
* The dropdown controls **which language you are currently editing**. All content you add or change is saved for that language.
* Text and other translatable fields (labels, placeholders, button text, etc.) are stored per language. The default language uses the normal property keys; other languages use language-prefixed keys internally.

So you switch the active language in the top bar, then edit normally: either in the **Options** panel (Content section) or by **clicking and editing text directly** in the preview. Both respect the selected content language.

## Setting languages

Languages are configured at the **Embeddable** level, not per page or component.

<Steps>
  <Step title="Deselect any selection">
    Click in empty space in the preview or press Escape so that nothing (no page, no component) is selected. The Options panel will show Embeddable-level options.
  </Step>

  <Step title="Open the Translations section">
    In the left sidebar, open the **Options** tab, then expand the **Translations** accordion section.
  </Step>

  <Step title="Add a language">
    Click **Add** and fill in:

    * **Key** – A short code for the language (e.g. <code>es</code>, <code>en\_us</code>, <code>fr</code>). The key should follow Embeddable's key name conventions, see [Naming keys](/guides/naming_keys).
    * **Name** – The display name (e.g. Español, English (US), Français). This is only used inside the builder.

    Click to add. The new language appears in the list below the default language.
  </Step>
</Steps>

* **Default language** – English is always the default and cannot be removed. It appears first in the list and does not have an Edit/Delete action.
* **Editing a language** – Use **Edit** on a language card to change its **Name** only. The **Key** cannot be changed after creation.
* **Removing a language** – Use **Delete** on a language card to remove that language. Content already stored for that language will no longer be shown to end users.

## Editing translations

After you have at least two languages, you can edit content per language in two ways.

### Switching the content language

When in **editing mode** and more than one language is configured, the **content language dropdown** appears in the top bar (next to the breakpoint toggle). It shows a short label for the current language (e.g. En, Es).

1. Click the dropdown and select the language you want to edit.
2. All subsequent edits (in the Options panel or in the preview) apply to that language until you switch again.

The selected language is remembered for your session in the Builder (stored in User Data for the Builder preview).

### Editing in the Options panel

1. Select the content language you want to edit from the top bar dropdown.
2. Select a component or page in the Layers sidebar or in the preview.
3. In the **Options** tab, open the **Content** section. Fields that support translations (text, label, placeholder, button labels, descriptions, etc.) will show and save values for the **currently selected language**.
4. Change any of those fields; they are stored for the active content language.

This applies to components that expose translatable fields in the Content section: **Plain Text**, **Rich Text**, **Rich Text Markdown**, **Custom HTML**, **Input Box**, **Option Selector**, **Custom Button**, **File Upload**, **Stripe Checkout** and **Media Image**.

### Editing text in the preview

You can also edit translatable text **in place** in the preview:

1. Select the content language from the top bar dropdown.
2. Click the text you want to change in the preview. The text becomes editable.
3. Type your changes. They are saved for the currently selected language.

In-place editing uses the same language as the dropdown, so you can work in one language at a time without opening the Options panel.

### Empty translations and fallback to default

When a translation field is empty for a given language, the default language (English) is shown instead. This applies to both the Builder preview and the published Embeddable.

**In the Builder, when editing in place:**

* If you switch to a language that has no translation yet, you see the default-language text. As soon as you **click into that text and edit it** (in the preview), you are now editing the translation for that language.
* If you **leave the field without making any change**, or if you **edit but then return the text to its original state** (e.g. with Ctrl+Z) before blurring, the translation stays empty and the default language continues to be shown.
* If you **make any edit**—even adding or removing a single space—and leave the field with the text changed, the translation is saved and the translated value is shown for that language.
* If you **clear the field** (e.g. with Ctrl+Z or by deleting all text) and then deselect the element, the translation is effectively empty again, so the default language is shown when you leave the field.

## End-user language

How an end user sees a given language depends on your setup. The runtime uses the value of <code>embeddable\_language</code> in [User Data](/features/user-data) (when present) to decide which language to show. You can:

* Set a default or detect locale and call <code>setUserData</code> (or equivalent) with <code>embeddable\_language: 'es'</code> (or another key you configured).
* Pass the language via a [URL param](/features/url-params) if you expose that key in your allowed URL keys.

### Letting users choose the language in the Embeddable

A common approach is to add an **Option Selector** (dropdown) somewhere on the page—for example in one of the corners—so end users can switch language themselves:

1. Add an **Option Selector** component and position it where you want (e.g. top-right or bottom-left).
2. Set the Option Selector's **key** to <code>embeddable\_language</code>. The selected value is then written to User Data and the runtime will show that language.
3. Add one **option** per language you configured: set each option's **key** to the corresponding language key (e.g. <code>en</code>, <code>es</code>, <code>fr</code>). Use the option labels for the display names (e.g. English, Español, Français).

Users can then pick their preferred language from the dropdown and the Embeddable content updates to that language.

If no value is present for <code>embeddable\_language</code>, or the provided value does not match any configured languages, the default language will be loaded.

## Related features

<CardGroup cols={2}>
  <Card title="User Data" icon="database" href="/features/user-data">
    Use User Data to drive which language the end user sees (e.g. embeddable\_language).
  </Card>

  <Card title="URL Params" icon="vial" href="/features/url-params">
    Prefill or override User Data (including language) via URL params.
  </Card>
</CardGroup>