Translating Content with DeepL

DeepL is a professional-grade AI translation service. Agility CMS offers a DeepL app, which an administrator installs on your instance. Once it is installed, the DeepL Translation Panel lets you translate individual content fields without leaving the content editor, and content can be translated as you make localized copies of pages, content items, or entire content lists.

This article covers the panel, and what does and does not get translated by either route. For the steps to copy content into another locale, see Copying and Translating Content Across Locales. For the bigger picture, see Working with Localized Content.

Prerequisites

Before using the DeepL Translation Panel:

• The DeepL app must be installed on your instance. If you don't see the translation panel, ask an administrator to install the DeepL app.

Opening the Translation Panel

The DeepL Translation Panel appears as a sidebar on the right side of the content editor. It is available in any locale, including your default one.

1. Navigate to the Content section

2. Select a content list and open a content item

3. Click the DeepL Translate icon in the right-hand sidebar

💡 Tip: the panel closes when focus moves elsewhere. Click the pin icon at the top right of the panel to keep it open while you work.

How Translation Works

Here's how to translate your content:

1. Check the Target Language

Translate to is pre-filled with the language of the locale you are currently in, so most of the time you can leave it alone. Editing in es-es pre-fills Spanish, and editing in en-us pre-fills English (US).

You can change it. Open the Translate to dropdown and pick any language DeepL supports, regardless of which locale you are editing in.

2. Select Fields to Translate

The panel lists the translatable fields on the item you are editing, by name, each with a checkbox. Check the fields you want to translate, or use Select All.

Only fields that can be translated appear in the list: text, rich text (HTML) and custom fields. Each custom field shows its type next to its name. Images, dates, numbers, dropdowns, linked content and code fields are left out, and so are custom fields that hold an identifier, such as a Friendly URL.

3. Translate

Click the Translate button to send the selected fields to DeepL for translation. The translated text will populate into the corresponding fields in the content editor.

Important: Translations are not automatically saved. After translating, review the results and click Save (or Publish) to keep the translated content. This gives you the opportunity to review and refine the translations before committing them.

If DeepL leaves a selected field unchanged, the panel lists it with the reason.

4. Clear Translations

If you want to undo the translations and restore the original field values, click the Clear button in the DeepL panel. This will revert the fields to their pre-translation state, as long as you haven't saved yet.

What gets translated, and what does not

This applies whether you translate with the panel or as part of copying content into another locale.

• Text is translated, including rich text, where links and formatting are preserved. Content copied into the target locale is translated along with the item, including its nested content.

• Custom fields are translated too. For a custom field that stores structured values (for example Power Fields' Markdown or Block Editor), only the readable text is translated. Keys, IDs, URLs and other identifiers are kept as they are. Whether a value is readable text is decided automatically, so review custom fields after translating.

• Images, dates, numbers and dropdown selections are copied unchanged. If an image contains words, you will want a localized version of it.

• Shared lists are not copied. Tags, categories and other shared content stay in the locale you built them in, deliberately: they are used across many items, so a single copy does not rewrite them. Localize those lists as their own task.

The two routes differ on when translations are committed. Translating fields with the DeepL panel while editing changes nothing until you save, so you can read the result and adjust first. Copying to another locale with translation enabled writes the translated item into the target locale as part of the copy, so you review it there.

Known limitations

• URL slugs in plain text fields are translated when you copy with Translate Content. Check slug fields in the copy before you publish it. Slug fields from apps, such as Power Fields' Friendly URL, are kept as they are.

• A copy doesn't list the fields DeepL kept as they are. Values that look like IDs, URLs or slugs are left unchanged without a note in the result. The DeepL panel does list them. Review custom fields in the copy.

• A page's URL path isn't translated. When you copy a page with translation, its title, menu text and meta description are translated, but its URL path is copied unchanged so links to it keep working. Change the path in the target locale if you want a localized URL.

Supported Languages

The languages you can translate into are the ones DeepL supports, and DeepL adds to that list over time. For the current list, see DeepL's supported languages.

Where DeepL has a regional version of a language, a regional locale gets it: Canadian French (fr-ca), Latin American Spanish (es-mx and other Latin American Spanish locales), Traditional Chinese (zh-tw and zh-hk), Brazilian and European Portuguese, and US and UK English. Other regional locales, such as en-ca or de-at, get the base language.

Tips and Best Practices

• Always review translations before saving. DeepL may not capture nuanced meaning, brand terminology, or culturally specific phrasing

• Translate field by field if needed. You can check individual fields rather than translating everything at once

• Use with Copy to Locales. First copy your default-locale content to other locales, then use DeepL to translate the copied content. See Copying and Translating Content Across Locales

• Rich text formatting is preserved. Links, bold, italic and other HTML formatting will be maintained through translation

Troubleshooting

• DeepL panel not visible: the DeepL app is not installed on your instance. Ask an administrator to install it

• The panel keeps closing: click the pin icon at the top right of the panel to keep it open

• Translate button disabled: make sure at least one field checkbox is selected

• Unexpected target language: Translate to is pre-filled from your current locale. Change it in the dropdown if you want a different language

• A copy came back untranslated: check the app's DeepL API key in Settings > Apps > Configure. It must come from a DeepL API plan (Translator, Write and Voice plans don't include API access), and the plan's monthly allowance mustn't be used up