> For the complete documentation index, see [llms.txt](https://help.mimeeq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.mimeeq.com/configurator/embeds-and-translations/translations.md).

# Translations

Manage and customise the interface text shown to customers across all your embed types. Learn how translation sets work, how to edit them, and how to assign them to embed templates.

Mimeeq's translation management system lets you control all UI text across your standard and modular configurators, basket, and other embed components — without touching any code. This article covers how translation sets work, how to create and edit them, and how to assign them to your embed templates.

## How translations work

Mimeeq uses a three-level inheritance system for translations:

| Level                   | Who manages it         | Description                                                                                                                                                           |
| ----------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Global Defaults         | Mimeeq (internal only) | Master translations maintained by the Mimeeq team. Not visible to customers. New keys are added automatically when new features are released.                         |
| Default Translation Set | You (customer admin)   | A copy of the global defaults, created automatically for your account. Can be customised per language.                                                                |
| Custom Translation Set  | You (customer admin)   | An optional copy of your Default translation set, used when you need different translations for specific embed templates (e.g. a B2B portal vs a Shopify storefront). |

**How inheritance works:**

* Every customer account starts with a **Default Embed Translation Set** that is automatically generated from the global defaults.
* If you have not overridden a translation key, any updates Mimeeq makes to the global defaults will flow through to your translation set automatically.
* If you **have** overridden a key, your custom value is preserved — global changes will not affect it.
* If you are still using the old JSON file method, that file takes precedence over all translation set settings. See [Migrating from the old translation method](#migrating-from-the-old-translation-method).

{% hint style="info" %}
In most cases, the Default Translation Set is all you need. Custom translation sets are useful when different embed templates require different wording.
{% endhint %}

## Setting up your languages

Translation sets cover all languages that are active in your account. Before editing translations, make sure your languages are configured correctly.

1. Go to **Settings → Customer Settings → Languages**.
2. Review the list of active languages. Each language shown here will appear as a column in your translation sets.
3. To add a new language, click **+ Add** and select the language from the list.
4. Tick the **Default Language** checkbox for the language you want to use as your primary language.
5. Click **Save changes**.

{% hint style="warning" %}
Translation sets only support languages that are active in your account. If you add a new language after your translation sets have been created, the new language column is added to your translation sets automatically.
{% endhint %}

![Setting up your languages in your account](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FzWyc4dJtZQxKMI9YWl3r%2Ftransaltion-1_1q73kdk.png?alt=media)

## Accessing your translation sets

1. Go to **Settings → Data → Translations**.
2. You will see a list of all translation sets in your account. Every account has at least one — the **Default Embed Translation Set**.
3. The **Connections** column shows how many embed templates are currently using each translation set. A set with existing connections cannot be deleted.

![Accessing your translation sets](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FTmIObaGHq7E8tnvISYEF%2Ftransaltion-2_bau17e.png?alt=media)

## Editing the default translation set

1. From the **Translations** list, click **Default Embed Translation Set** to open it.
2. You will see a flat list of all translation keys. Each row includes the following columns:

* Translation key — the key identifier (read-only)
* Where is displayed — the area of the embed where the key is used (e.g. AR Viewer, Configurator, Basket)
* Description — a short explanation of what the key controls, to help you identify the right one
* One editable column for each of your active languages

3. Use the **Search** field to find a specific key. You can also use the **filter dropdown** (set to **All Keys** by default) to narrow the list by category (System or Custom).
4. Toggle **Show only edited** to ON to filter the grid to only keys you have manually overridden. This is useful for reviewing your customisations.

![Default Embed Translation Set Example](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2F0cxCyIYuzim2uoufJV93%2Ftransaltion-3-new_siiaqn.png?alt=media)

### Working with more than 10 languages

To keep the grid fast to load, Mimeeq displays a maximum of 10 language columns by default. If your account has more than 10 active languages, a **Language Visibility** button will appear in the top-right corner of the translation set page.

1. Click **Language Visibility** to open the language selector panel.
2. Your active languages are listed with checkboxes. The first 10 are selected by default.
3. Tick any additional languages you want to display in the grid, or use **Select all languages** to show all at once.
4. Click **Apply**. The selected languages appear as additional columns in the grid.

{% hint style="info" %}
Language Visibility is only shown if your account has 11 or more active languages. If you have 10 or fewer, all language columns are always visible.
{% endhint %}

## Editing a translation key

1. Click any row in the translation grid to open the **Edit translation key** modal.
2. At the top, the **Key Settings** section shows three read-only fields:

* **Translation key** — the key identifier
* **Where is displayed** — the area of the embed where this key appears
* **Description** — what the key controls

3. Below Key Settings, each of your active languages appears as a separate section. The **Default value** shown in grey is the Mimeeq system default for that key.
4. To override a value, click **Override default value** under the relevant language. The text area becomes editable.
5. Enter your custom translation text.
6. If you want to revert a language back to the system default, click **Reset to default**.
7. For non-default languages, you can click **Fill from \[default language]** to quickly copy the default language value into that language's field as a starting point.
8. Click **Apply changes** when you are done.
9. Click **Save changes** at the bottom of the page to save all your edits.

![Edit Translation Key Modal](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FLvCBIPOewTK3wcdGpIki%2Ftransaltion-4-new_1e5zax6.png?alt=media)

## Creating a custom translation set

You only need a Custom Translation Set if you want different translations assigned to different embed templates (for example, a different tone of voice for a B2B portal versus a consumer-facing store). For most accounts, the Default Embed Translation Set is sufficient.

1. Go to **Settings → Data → Translations**.
2. Click **+ New**.
3. Enter a name for the new translation set (e.g. `Shopify Store` or `B2B Portal`).
4. Click **Save**. The new set opens with the same grid as the Default Embed Translation Set, pre-populated with all the same values.
5. Edit translation keys as needed following the steps in [Editing a translation key](#editing-a-translation-key).

### Renaming, duplicating, or deleting a custom translation set

Open the translation set and click the **⋮** menu in the top-right corner. You can:

* **Rename set** — change the display name of the set
* **Duplicate** — create a copy of the set as a new custom set
* **Delete** — permanently remove the set

{% hint style="warning" %}
A translation set assigned to one or more embed templates cannot be deleted. Remove the assignment from all embed templates first.
{% endhint %}

## Managing custom keys

Custom keys let you define your own translation keys for UI elements specific to your implementation that are not covered by the standard Mimeeq keys. In the translation grid, system-provided keys are labelled with a **System** tag and your custom keys are labelled with a **Custom** tag.

You can only create keys with the `custom.` prefix. This is how the system distinguishes your keys from Mimeeq-managed ones. If you need a new translation key for your own UI, it must use the `custom.` prefix (e.g. `custom.downloadButton.label`).

### Adding a custom key

1. Open any translation set and click **New** in the top-right corner.
2. In the **Add translation key** modal, enter the **Translation key** name. The key must start with the `custom.` prefix (e.g. `custom.downloadButton.label`). Use letters, numbers, dots, and underscores only — no spaces or special characters.
3. Optionally, fill in **Where is displayed** and **Description** to help you and your team identify what the key is used for.
4. Enter the translation value for each of your active languages.
5. Click **Save**. The key appears in the translation grid with a **Custom** tag in the Source column.

![Create Custom Key Modal](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FrmZSUGlEAqT04BjRiBJa%2Ftransaltion-5-new_1ml073n.png?alt=media)

### Editing a custom key's translation values

Click any row in the **Custom keys** grid to open the edit modal. All language fields are directly editable — there is no default value to override, since these keys are unique to your implementation.

### Renaming a custom key

Click the key name in the grid to open the **Edit translation key** modal. Enter the new key name and click **Save changes**.

{% hint style="warning" %}
If the key is already referenced in your custom UI code, renaming it will break those references and cause missing translations. Only rename a key if you also update the corresponding key name in your codebase.
{% endhint %}

### Deleting a custom key

1. Click the delete icon on the row you want to remove.
2. A confirmation modal will appear. Type `DELETE` in the field to confirm.
3. Click **Delete**.

{% hint style="warning" %}
Deleting a custom key removes all associated translations across all languages. Any part of your custom UI referencing that key will show a missing translation. This action cannot be undone.
{% endhint %}

## Importing and exporting translations via CSV

CSV import and export lets you update translation keys in bulk — useful when making changes across many languages at once, or when adding a large number of custom keys for a custom UI. The feature works for all translation keys, both standard and custom.

The recommended workflow is: **export → edit in a spreadsheet → re-import.**

### Exporting translations to CSV

1. Open a translation set and click **Export to CSV** in the top-right area of the page.
2. A CSV file will download containing all translation keys — both standard and custom — with one column for `translationKey` and one column per language code (e.g. `en`, `de`, `pl`). Always start from an export rather than building a CSV from scratch — it ensures the file is correctly formatted and contains all existing keys.

![Recommended workflow: export → edit in a spreadsheet → re-import](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2FFXIBVUPiy18ffIsy10pe%2Ftransaltion-6-new_pt5c2u.png?alt=media)

### Preparing your CSV for import

Open the exported CSV in a spreadsheet editor and make your changes:

* To **edit an existing standard key**, find the row by its `translationKey` value and update the relevant language columns.

{% hint style="warning" %}
You can only create new keys with the `custom.` prefix. Attempting to add new rows with any other prefix — such as `ar.`, `configurator.`, or `basket.` — will be rejected during import. You can edit the translation values of existing standard keys, but you cannot create new ones.
{% endhint %}

* To **add a new custom key**, add a new row. The `translationKey` value must start with the `custom.` prefix (e.g. `custom.downloadButton.label`). Custom keys without this prefix will fail validation and will not be imported.
* Leave any cells you do not want to change blank or unchanged — those values will be skipped during import.

{% hint style="warning" %}
Do not edit the values in the `translationKey` column for any existing keys. Translation keys are references used throughout your embed templates and custom UI. Modifying a key name will not rename it in the system — it will be treated as a new key, and any existing references to the original key will result in missing translations.
{% endhint %}

### Importing your CSV

1. Open the translation set you want to update.
2. Click the dropdown arrow next to the **New** button and select **Import CSV**.
3. In the **Import translations (CSV)** modal, drag and drop your CSV file into the upload area, or click **upload file** to browse.
4. Click **Import**.

After processing, a results summary is shown indicating how many records were processed, skipped, and how many had errors. Any rows that failed validation — for example, custom keys missing the `custom.` prefix, or unrecognised key names — are listed with their error details below the summary.

5. Review the results. If there are errors, close the modal, correct your CSV, and re-import.
6. If the results look correct, close the modal. Your changes are shown as a preview in the grid — they have not been saved yet.
7. Click **Save changes** at the bottom of the page to apply your changes.

## Assigning a translation set to an embed template

By default, all your embed templates are assigned the **Default Embed Translation Set** automatically. You only need to change this if you have created a custom translation set for a specific template.

1. Go to **Settings → Data → Embed Templates**.
2. Click the embed template you want to update.
3. In the left-hand settings panel, find the **Preview Settings** section and click to expand it.
4. Locate the **Translation Set** dropdown.
5. Select the translation set you want to use from the dropdown.
6. Save your template.

![Assigning a translation set to an embed template](https://621103948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsqWfi8ifBhTdkvf1vOlY%2Fuploads%2Fw2kZJ39U6ki8ASrD4EQz%2Ftransaltion-7_188ymk3.png?alt=media)

## Migrating from the old translation method

If your account was set up before the translation management feature was introduced, the behaviour depends on whether you were using the old JSON-based translation override method.

**If you were not using the old method (no custom translation JSON files on your templates or website):**

The new Default Embed Translation Set has been automatically applied to all your embed templates. No action is needed — you can start managing translations directly from **Settings → Data → Translations**.

**If you were using the old method (custom translation JSON files on your templates or website):**

Your existing JSON overrides take precedence over the translation set settings. Any keys defined in your JSON file will continue to be used, and changes you make in the translation management interface will not be reflected until you remove the JSON file.

### To fully migrate to the new system:

1. Export or note down all the custom translations from your existing JSON file.
2. Remove the custom translation JSON file from your website code **or** remove it from the relevant embed template settings.
3. Re-enter your custom translations using the translation management interface, either as overrides on existing keys or as new custom keys in the **Custom keys** tab.
4. Assign the updated translation set to your embed templates as described in [Assigning a translation set to an embed template](#assigning-a-translation-set-to-an-embed-template).

{% hint style="info" %}
If you have a large number of keys to migrate, use the CSV import/export workflow rather than editing keys one by one. Export your Default translation set to CSV, update the relevant keys in your spreadsheet editor, then re-import. See [Importing and exporting translations via CSV](#importing-and-exporting-translations-via-csv) for full instructions.
{% endhint %}

{% hint style="warning" %}
Do not remove the JSON file until you have recreated your translations in the new interface, otherwise your users will see default or missing translations until the migration is complete.
{% endhint %}

## Related articles

* [Embed Types](/configurator/embeds-and-translations/embed-types.md)
* [Embed Template Settings](/configurator/embeds-and-translations/template-settings.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.mimeeq.com/configurator/embeds-and-translations/translations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.