Template Translation

Template Translation uses AI to translate your email templates into any language. You can translate the entire template at once or go block by block. The translation preserves your styling, structure, Merge Tags, and original tone.

It uses the same OpenAI integration as the AI Assistant, so if the AI Assistant is already configured, translation works without any extra setup.

Prerequisites

Before using Template Translation, ensure a valid OpenAI API key is configured in your Plugin API Token settings. Follow the instructions in this article to connect your OpenAI API key to your Topol Plugin.

How it works

There are two ways to translate content:

1. Whole-template translation

This translates all text and button blocks at once. There are two places to trigger it, depending on whether Multilingual Templates is enabled.

From the Top Bar (multilingual disabled)

When Multilingual Templates is not enabled, a Translate button appears in the top bar. Click it, pick a target language from the dropdown, and the whole template gets translated.

From language settings (multilingual enabled)

When Multilingual Templates is enabled, you translate content from the language settings panel, where the result is saved directly into a mutation's translations. There are two ways to do this — translate a single mutation, or translate every mutation at once.

Translate a single mutation

Each language mutation has its own translate icon button. Clicking it translates the template content into that mutation. There are two ways to choose where that content is translated from.

Translate from primary (default) — Click the translate icon to translate the mutation from the primary language. This is the default behavior, and the only option when the template has a single mutation.

Translate from a selected mutation — When you have more than one mutation, the translate icon becomes a split button: a caret next to it opens a small "Translate from" menu listing every defined mutation. Pick one to translate that mutation's content from the language you chose rather than from the primary.

Choosing a non-primary source is useful when you've made edits in a specific mutation and want to push them into the others, instead of always starting from the primary copy.

Translate all mutations from primary

The language settings panel header has a Translate all button. It translates every non-primary mutation in one pass, each from the primary language, after a confirmation prompt. Existing translations in those mutations are overwritten, and the whole batch is grouped into a single undo step, so one Undo reverts every mutation at once.

2. Block-level translation

You can also translate individual text or button blocks through the AI context menu. A Translate option now sits alongside Improve, Rephrase, Make Longer, and Make Shorter.

If you're using Multilingual Templates, the block translates into the active language automatically.

Otherwise, a language selector dropdown appears so you can pick the target language.

Custom Language Preset

By default, the language dropdown shows our predefined set of languages. You can replace or extend this list with your own languages using the customLanguagePreset option. See Custom Language Preset for configuration details.

Top Bar visibility

The translate button in the Top Bar is controlled by topBarOptions. If you're using topBarOptions to selectively show Top Bar elements, include "translate" in the array:

const TOPOL_OPTIONS = {
  topBarOptions: [
    "undoRedo",
    "save",
    "changePreview",
    "translate", // show the Translate button in the top bar
  ],
};

If topBarOptions is not set or is an empty array [], all elements show by default, including the Translate button. See Top Bar And Window Bar for more on top bar customization.

INFO

The Translate button in the Top Bar only appears when Multilingual Templates is not enabled. When Multilingual is on, you access translation through the language settings panel instead.

Triggering translation from your own UI

If you manage language mutations from outside the editor iframe (see External Language Management), you can trigger translation programmatically through the Plugin's public API. This lets you wire translation into your own buttons or workflows instead of relying on the editor's UI.

Available Methods

Method	Description
TopolPlugin.translateLanguage(lang, sourceLang?)	Translates a single mutation, identified by its language code. By default the source is the primary language; pass sourceLang to translate from a specific mutation instead.
TopolPlugin.translateAllLanguages()	Translates every non-primary mutation from the primary language in one pass. Existing translations are overwritten.

// Translate the German mutation from the primary language
TopolPlugin.translateLanguage("de");

// Translate the German mutation from the French mutation
TopolPlugin.translateLanguage("de", "fr");

// Translate every non-primary mutation from the primary language
TopolPlugin.translateAllLanguages();

These methods behave exactly like the in-editor controls described above: they require a configured OpenAI API key, write the result directly into the mutation's translations, and group their changes into the undo history.

For the full list of callable Plugin functions, see the Topol Plugin reference.

INFO

translateLanguage and translateAllLanguages operate on multilingual mutations, so they require Multilingual Templates to be enabled. If the target language is not one of the template's existing mutations, the editor reports that the language was not found and makes no changes.

Related features

• Multilingual Templates: manage multiple language versions of a template. Template Translation writes directly into multilingual mutations.
• AI Assistant: the inline writing assistant for improvements, rephrasing, and length changes. Translation is an action in the same AI context menu.
• Custom Language Preset: define your own list of available languages in the translation dropdown.