---
title: Optimizely Languages gadget
slug: cms-13/docs/optimizely-languages-gadget
docTags: 
createdAt: 2026-07-30T20:22:03.890Z
---

The Optimizely Languages gadget manages languages and content translations on multilingual websites. Activate languages, manage language branches, translate content, and compare language versions from a single gadget. The gadget also supports automated content translation through a third-party service.

:::hint{type="info"}
**Note**
The [Optimizely Digital Experience Platform (DXP)](https://docs.developers.optimizely.com/digital-experience-platform/docs/optimizely-digital-experience-platform) contains features to support your daily work. Depending on how your solution is configured, some features described in this documentation are not available.
:::

An administrator installs and configures the Optimizely Languages add-on. After configuration, add Optimizely Languages as a gadget to your workspace.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/8_y0iFluD6ghzKRY5poSS_e5707418bbd209d575f158ba78897a45722c6ac5905bfa96878ec8fa2d7a4be1-image.png)

## Configure languages in the gadget

Configure languages in the gadget to enable content creation in additional languages and to assign editor access rights.

A system administrator adds a language to the website and activates it before editors create content in that language.

### Activate a language from the gadget

1. Select **Manage Languages** from the Optimizely **Languages** gadget options.
2. Click the language link in the list. Add a missing language if needed.
3. Select **Enabled** to activate the language. Under **Users/groups for creation and editing**, assign access rights for a specific editor (such as *erin*) or group (such as *CmsEditors*). Each language is available to the **Everyone** group by default. Remove this group to restrict access.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/41sCaV-rMpzPDg1s6she0_035036fbf469f6fb018967404f96918b43001ba5cd78e002963f880c7bc2804f-image.png)

4. Click **Save Language** to close the **Manage Website Languages** dialog box. The language is active on the website and displays in the Optimizely Languages gadget but is not yet available for content creation.

### Enable a language for editing from the gadget

Languages inherit settings from the parent page by default. When you enable a language for a parent page, the language is also enabled for subpages. Override this behavior at any level of the page tree.

1. Select the page from which you want the language setting to apply in the page tree navigation.
2. Select the language to activate in the Optimizely Languages gadget.
3. Select **Enable editing for \[*language*]** from the context menu.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/03ecmPGe4AxRYAomSxY-L_11d49b59b8ae52856841b6f374fbced90b28920a9fa1b0097ca3dfe7065db0b9-image.png)

Select **Manage Editable Languages for this Content** in the **Languages** gadget to open the **Language Settings** dialog box. This dialog box is also where you define **fallback** and **replacement** languages for the website. Go to [Configure a fallback language](docId\:PtNcccZmCXTI4Hr3BA8jY) for details.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/BZEwxL6xThJ4Zfskr0dKC_287b2166a1f22156d2f037328c40e0d920d486355769660bd54ad64db81c5cb5-image.png)

### Connect to the auto-translation service

Configure the auto-translation service to enable automated content translation through Microsoft Azure Cognitive Services.

1. Subscribe to Azure.
2. Register Translator from Cognitive Services.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/RAEneQYF-L_1VZYv37Lqy_03f17fd4476282bfe3a51152727e70c945ac1919d2f19a0cf5695121f8b92feb-image.png)

3. Configure the auto-translate component in Optimizely Languages. Go to **Settings** > **Languages**.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/-i0xqn5P90ZRt9j9Xn_rM_05188eab678583e7eb9667a8e9b397305db01057fa7206f1dee7ab391160d0fc-image.png)

:::Paragraph{listStyleType="disc" indent="2"}
**Translator Provider** – Select **Cognitive Service Translator**.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Subscription Key** – Enter the Microsoft subscription key (**Key 1**) from the Azure subscription service.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Subscription Region** – Enter the **Location** value from the Azure subscription service.
:::

4. Click **Save**.

## Use Optimizely Languages

Use the Optimizely Languages gadget to translate pages and blocks, compare language versions, and manage content across languages.

### View parts of a website in a selected language

1. Select a page from the page tree.
2. Click **Show All Languages** in the navigation panel to see pages that do not exist in the selected language. Untranslated pages display in italics. Replacement or fallback languages (if applied) also display.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/sg6x8G1vZDpupGDsXDo3t_a446c568bbb2a2450655afd929e1c7f815830dce0997533b8302beacdc55eca8-image.png)

### Translate content

Translate a page or block using one of the available translation methods.

1. Select the page to translate in the page tree, or open a block from the assets panel.
2. Click **Create** in the Optimizely **Languages** gadget.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/DyFC2txOURVaG6EifJqAv_96507860020824b9e7db2577fb13c55fab75ebe68baca43f85fbb5669ac1e227-image.png)

3. Select from the following translation options:
   - **Auto-translate** – CMS translates content from the master language. This option is available only when the auto-translate component is configured on your website. Go to [Configure auto-translation](docId\:muqlHeANh2QLkgHacA5IU) for details. Review the result before publishing.
   - **Duplicate content** – Copies content from the master language for manual translation.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/fEx-6cDwPTLBVW9CaCNV7_ed23f661d78036fe16928d6f77b29b967b543f5b6d2b6acd061c5610979a5fbc-image.png)

:::Paragraph{listStyleType="disc" indent="2"}
**Start with a blank page** – Creates a blank page or block with the title from the master language. Add translated content manually.
:::

4. Add translated content as appropriate.
5. Review and publish the page or block according to the publishing flow in Optimizely CMS.

:::hint{type="info"}
**Note**
Language versions are created as drafts. Review and publish them manually.
:::

### Replace content with the master language

Replace translated content with the original master language content when a translation is outdated or incorrect.

1. Select the translated page in the page tree.
2. Select the language to replace.
3. Click **Replace Content** to confirm the action.

:::hint{type="danger"}
**Warning**
This action cannot be undone.
:::

### Create a page in a different master language

Create a page that exists only in a specific master language.

1. Select the target language in the Optimizely Languages gadget or the tab in the navigation panel.
2. Select the parent page where you want to create the page in the page tree navigation.
3. Select the page type and enter a page name.
4. Review and publish the page according to the publishing flow in Optimizely CMS.

### Compare language versions

Compare a page side by side in two language versions to review auto-translated content or translate content manually.

1. Select an existing page to translate in the page tree.
2. Select the translation language and the **Compare with \[*master language*]** option in the Optimizely Languages gadget.
3. Edit the content in the selected language. The master language page is read-only in this view.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/bAAHeAIZFo5-8XGRcTWgd_af9342d2a4390bbc26647274b1dff062ddbf1d9aac758319b2f08e8da9f0ffd9-image.png)

4. Review and publish the page, or click **Close Compare** or **Replace Selected Content**.

### Delete a language version

:::hint{type="danger"}
**Warning**
This action cannot be undone.
:::

1. Select the page from which you want to delete a language version in the page tree.
2. Open the **Versions** gadget and select the language version.
3. Confirm the deletion.

:::hint{type="info"}
**Note**
Deleting the master language version requires deleting the entire page.
:::

## Import and export XLIFF files

Use XML Localization Interchange File Format (XLIFF) files to send content for external translation and import the translated content back into CMS. This workflow is useful when working with professional translation services or tools.

Add a content item (such as a page or block) to a translation project by drag and drop or through its context menu. Download a zip file containing the project items in XLIFF format and send it for translation.

![Screenshot of the translation project overview where you add content items and download XLIFF packages](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/ccgFHr3XgT1v5lIEQfco0-20260722-195713.png)

When translations are complete, upload the translated zip file to the server. A scheduled job imports the content. The following behaviors apply:

- CMS displays a notification in the UI after importing a translation package.
- CMS stores uploaded translation packages in the translation folder under the module root.
- The translation process affects only draft versions.

To create a translation project and add content, follow these steps:

1. Select **New Project** from the **Project** menu to create a project for the translation.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/onMNlTjAwnm0QvY7svKFo_33961a0a49f98d597cd435bbe8d1bde4f3189d19a828fa8bafa573b1970b7ac6-image.png)

2. Enter a project name and click **OK**. The project is enabled automatically.

![Screenshot of the New Project dialog box where you enter a project name](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/tGmb3k6kNIVRrZXXEEEx7-20260722-195713.png)

3. Select the page to translate in the page tree.
4. Click **Create** for the language to translate in the **Languages** gadget.

![Screenshot of the Languages gadget where you click Create for the target translation language](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/-kTNpc0kZitZhBpynJRMm-20260722-195713.png)

5. Select **Duplicate English content**. Starting with a blank page is also an option. CMS adds the version to your translation project automatically.

:::hint{type="info"}
**Note**
Do not publish the page during this step.
:::

6. (Optional) Select **More** > **Add to Translation Project** to add an existing target language version to a translation project. An **Add to translation** dialog box displays.
7. Specify the content to add to your translation project.

![Screenshot of the Add to translation dialog box where you select the project and content options](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/mresdBvQcizo6KacJ4Osa-20260722-195713.png)

:::Paragraph{listStyleType="disc" indent="2"}
**Add to translation project** – Select the project to work with.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Add all children** – Add references to the descendants of the content to the project.
:::

:::Paragraph{listStyleType="disc" indent="2"}
**Add related content that needs a translation** – Add related content items to the project.
:::

:::hint{type="info"}
**Note**
Combine children and related content in the translation project. CMS notifies you if an item is already part of another project.
:::

8. Go to the **Project** menu and click **Overview** after adding content to your translation project.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/UZ1q-8JXjUMIEXBOn8E0h_d9d2b8103e3c9409963458beb7339001937eb70802c8856586c879e47074a355-image.png)

9. Select **Options** > **Download Translation Package**. CMS downloads a zip file containing XLIFF-formatted content. Send the package for translation.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/UD3DR0lxoele_44GnvO9M_cbfc3911d7d0e9c4bddfa86982260657a8dfbf32086bcc56af0eecb5b1a70fd0-image.png)

### Import translation package

Import translated content back into CMS after external translation is complete.

:::hint{type="warning"}
**Important**
Verify the zip file does not include any folders before uploading.
:::

1. Enable your translation project and select **Options** > **Upload Translation Package(s)** to upload the zip file to the server.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/UQ25KGxNcUkH_5Ye6Gbou_4a0f81099fd53402e362153af89282e81bfef29f14ab570f38d19a82d4d23d50-image.png)

2. Wait for the scheduled job to import the packages. To start the import manually, go to **Settings** > **Scheduled Jobs** > **Import Translation Packages** > **Details** > **Start**.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/r0Cqceghv1pC3za849kRz_e0708b35ad88f14deeac8e8193e70e66aabcf2db1966c4dbc93f7b79663e81f4-image.png)

CMS sends a notification to the project owner when the import is complete.