Multilingual Templates

This feature is available with the Plugin for Business plan and higher.

If you're on the Plugin for Startup or Plugin Expansion plan, consider upgrading to access this feature. For more details, visit our pricing page or contact support.

The Multilingual Templates feature lets you create multiple language versions (mutations) of the same template. Instead of creating and managing separate HTML and JSON files for each version, the feature saves a single JSON file that contains both the main (primary) template structure and all text translations for each defined mutation.

When you need HTML output for a specific language mutation, send the multilingual JSON along with the selected language code to a special API endpoint. The endpoint then returns the corresponding HTML. The list of available languages for the template is stored in a mutations array, which is always included alongside html and json when saving a multilingual template via the onSave callback.

How to Enable

To activate the Multilingual Templates feature, add the following option to your TOPOL_OPTIONS configuration object:

multilingual: true,

Once enabled, the editor’s Top Bar will display a Create mutation dropdown.

This dropdown serves as the main hub for managing all language variations in the Plugin UI. It allows you to create, switch, and delete mutations, or change which mutation is marked as Primary.

Workflow Example

When the editor opens with the Multilingual feature enabled, the user can begin in two ways:

• Design the template first and then create a language version (mutation), or
• Create a mutation first and then start designing.

In both cases, the current template becomes linked to that mutation.

Once the first language version is ready, the user can add another language and select it. Initially, the new mutation looks identical because no content in that language has been added yet. While that language is active, the user can rewrite the content in the chosen language. This process can be repeated for any number of languages. When switching to a mutation that already has content, the editor instantly loads that version.

One language must always be marked as Primary, serving as the default version. The Primary language cannot be deleted, but its role can be reassigned to another mutation at any time. The Primary flag is especially important when saving the template (explained later). If a non-Primary mutation is deleted, the editor automatically returns to the Primary version.

Saving Multilingual Templates

When the user saves the multilingual template via the default or custom Save button, the onSave callback always receives three parameters: json, html, and mutations.

onSave callback structure:

const TOPOL_OPTIONS = { 
  callbacks: { 
    onSave(html, json, mutations) { 
      // Implement your save logic here.
      // If multiple mutations exist,
      // define how to store each language version.
    },
  }, 
};

If your onSave callback integration currently only handles json and html, you must extend it to also process the mutations parameter in order to support multilingual templates feature.

Even if no mutations exist (or if the Multilingual feature is not enabled), the mutations parameter will still be passed. However, in these scenarios, it will be an empty array [], which can be ignored.

Parameter details:

The HTML you receive depends on how the save action is triggered:

1. Saving with the default Save button

The onSave callback always returns only the HTML of the Primary mutation. Even if other mutations exist, they are not included.

To get HTML for specific mutations, you must call the API endpoint (explained in the next section).

2. Saving with your custom Save button

If you implement your own Save button, it must call this function:

// The lang parameter is a language code and is optional
window.TopolPlugin.save(lang?: string);

This call then triggers the usual onSave(html, json, mutations) callback, but the optional lang parameter gives you control over the HTML output:

• If you include the lang parameter, you receive the HTML output of that specific mutation.

• If you omit it, you receive only the HTML output of the Primary mutation.

INFO

You need to know the lang value before calling window.TopolPlugin.save(lang).

To handle this, create your own mechanism that lets users choose a language, such as a dropdown or selector. Store the selected language in your application state, and when the user clicks your custom save button, pass that stored value into the lang parameter of window.TopolPlugin.save(lang).

The mutations array, which contains information about available language mutations, is only returned inside the onSave(html, json, mutations) callback. Because this happens after the window.TopolPlugin.save(lang) call, you cannot rely on the mutations array to decide which language to save.

The json parameter matches the structure of the Primary mutation. It also includes a special langs array that holds all defined language mutations and their translations.

Example:

// ...Primary mutation JSON
"langs": [
  {
    "key": "en",        // Language code
    "primary": true,    // false if not the primary mutation
    "translations": {   // All translated blocks for this mutation
      "ZF-vfFO4c": {    // UID of a block (same as in the primary)
        "content": "<p>Content in English.</p>" // Its content in this mutation
      },
      "w5ubrEmMN": {    // UID of another block (same as in the primary)
        "content": "Click me!", // Its content in this mutation
        "attributes": { // Its attributes in this mutation
          "href": "https://google.com"
        }
      }
      // ...other translated blocks in this mutation
    }
  },
  // ...other language mutations
]

This structure ensures that all language-specific content is stored on one place (in this multilingual JSON file) alongside the Primary template.

The mutations parameter is always an array containing information about all language mutations defined in the current multilingual JSON. Each object inside this array holds only the language code and whether this language is Primary.

Data structure:

mutations: {
  lang: string,
  primary: boolean
}[]

Example:

[
  {
    "lang": "en", // language code
    "primary": true
  },
  {
    "lang": "de",
    "primary": false
  },
  // ...other mutations stored in multilingual JSON
]

API Endpoint for Retriving Specific HTML Mutations

When saving a multilingual template, you may be tempted to call window.TopolPlugin.save(lang?: string) inside the onSave(html, json, mutations) callback for every language in the received mutations array.

However, this approach is strongly discouraged. Each call to window.TopolPlugin.save(lang?: string) triggers another onSave callback, which would create an infinite loop.

Instead, use the dedicated API endpoints that return the requested HTML mutation on demand:

...