Документация

Перевод контента

Отметьте контент, который хотите перевести, Magic Translate. Исходное содержимое отображается до загрузки перевода.

Элемент <t>

Поместите текст в элемент <t>, чтобы перевести его. Он может содержать код 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> также работает, если вы предпочитаете настраиваемое имя элемента.

Атрибут data-t

Если вы не можете добавить элемент-оболочку, добавьте data-t к существующему элементу, чтобы перевести его содержимое:

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


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

Атрибуты

Перечислите атрибуты для перевода в data-t-attrs, разделенные пробелами:

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


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

Переменные

Поместите изменяющиеся значения, такие как имя или количество, в data-v в виде объекта JSON и указывайте на них как $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 переводит текст вокруг значений один раз, как Hi {0}, you have {1} new messages, и возвращает значения на страницу. Перевод кэшируется и работает для каждого имени и каждого числа, а сами значения никогда не отправляются в Magic Translate.

Чтобы показать новые значения, измените data-v. Кэшированный перевод используется повторно без запроса:

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

Значения нумеруются в том порядке, в котором они появились впервые. Перевод позволяет перемещать их туда, где они нужны языку, например {1} neue Nachrichten für {0}.

Несколько правил:

  • Заменяются только клавиши data-v, поэтому текст, например $5, остается без изменений. Если две клавиши, например count и counts, начинаются одинаково, выигрывает самая длинная клавиша.
  • Одно и то же имя может появляться несколько раз.
  • Значения вставляются в виде текста, а не в формате HTML. Вместо этого поместите пометку в текст вокруг них: Hi <b>$name</b>.
  • В содержимом переменные заменяются только текстом, а не такими атрибутами, как href или title.
  • Если data-v не является действительным объектом JSON, текст остается непереведенным, а предупреждение регистрируется. Клавиша, которая не отображается в тексте, также выводит предупреждение.
  • $name отображается до тех пор, пока скрипт не загрузится. Загрузите скрипт в начале страницы или скройте эти элементы до тех пор.

Опции

Используйте эти атрибуты для задания опций для одного элемента:

АтрибутЦенностьОписание
data-formalityinformal или formalУстанавливает формальность перевода.
data-langкод языкаПереопределяет язык страницы.
data-t-idудостоверение личностиПозволяет редактировать это использование текста самостоятельно. Это относится к содержимому элемента, а не к хэштегу data-t-attrs.
<t data-lang="fr" data-formality="formal">How are you?</t>

Контент, который меняется

Содержимое, добавленное на страницу позже или измененное вашими скриптами, также переводится. Это работает с контентом, созданным с помощью JavaScript, например, с помощью htmx или jQuery.

Все переводы, запрошенные одновременно, отправляются в API одним запросом, а переводы кэшируются. Вы можете пометить любое количество элементов.

Ограничения

Содержимое одного элемента не может превышать 10 КБ, что составляет около 5000 символов. Вложенные элементы переводятся как часть родительского элемента <t>.

ПредыдущееJavaScriptСледующийAPI JavaScript