Documentation

Translating content

Mark the content you want Magic Translate to translate. The original content is shown until the translation loads.

The <t> element

Put text in a <t> element to translate it. It can contain HTML:

<t>This content will be translated</t>


<t>Click <a href="/sale">here</a> to see <b>today's</b> deals.</t>

<mt-translate> works as well, if you prefer a custom element name.

The data-t attribute

If you cannot add a wrapper element, add data-t to the existing element to translate its content:

<title data-t>My online shop</title>


<select>
  <option data-t>Small</option>
  <option data-t>Large</option>
</select>

Attributes

List the attributes to translate in data-t-attrs, separated by spaces:

<input placeholder="Search products" data-t-attrs="placeholder" />


<img src="team.jpg" alt="Our team" title="Say hi" data-t-attrs="alt title" />

Variables

Put values that change, such as a name or a count, in data-v as a JSON object, and reference them as $name:

<t data-v='{"name": "Bob", "count": 7}'>Hi $name, you have $count new messages</t>


<input placeholder="Search $count products" data-t-attrs="placeholder" data-v='{"count": 3}' />

Magic Translate translates the text around the values once, as Hi {0}, you have {1} new messages, and puts the values back in the page. The translation is cached and works for every name and every count, and the values themselves are never sent to Magic Translate.

To show new values, change data-v. The cached translation is reused and no request is made:

element.dataset.v = JSON.stringify({ name: 'Bob', count: 8 });

The values are numbered in the order they first appear. The translation can move them wherever the language needs them, for example {1} neue Nachrichten für {0}.

A few rules:

  • Only keys of data-v are replaced, so text such as $5 stays as it is. If two keys start the same way, such as count and counts, the longest one wins.
  • The same name can appear more than once.
  • Values are inserted as text, never as HTML. Put markup in the text around them instead: Hi <b>$name</b>.
  • In content, variables are replaced in text only, not in attributes such as href or title.
  • If data-v is not a valid JSON object, the text is left untranslated and a warning is logged. A key that does not appear in the text logs a warning too.
  • $name is visible until the script has loaded. Load the script early in the page, or hide these elements until then.

Options

Use these attributes to set options for a single element:

AttributeValueDescription
data-formalityinformal or formalSets the formality of the translation.
data-langa language codeOverrides the language of the page.
data-t-idan idLets you edit this use of the text on its own. It applies to the element's content, not to its data-t-attrs.
<t data-lang="fr" data-formality="formal">How are you?</t>

Content that changes

Content added to the page later, or changed by your scripts, is translated as well. This works for content rendered by JavaScript, for example with htmx or jQuery.

All translations requested at the same time are sent to the API in a single request, and translations are cached. You can mark as many elements as you like.

Limitations

The content of a single element cannot exceed 10 KB, which is about 5,000 characters. Nested elements are translated as part of their parent <t> element.

PreviousJavaScriptNextJavaScript API