Documentação

Traduzindo conteúdo

Marque o conteúdo que você deseja que Magic Translate traduza. O conteúdo original é exibido até que a tradução seja carregada.

O elemento <t>

Coloque o texto em um elemento <t> para traduzi-lo. Ele pode conter 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> também funciona, se você preferir um nome de elemento personalizado.

O atributo data-t

Se você não conseguir adicionar um elemento wrapper, adicione data-t ao elemento existente para traduzir seu conteúdo:

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


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

Atributos

Liste os atributos a serem traduzidos em data-t-attrs, separados por espaços:

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


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

Variáveis

Coloque valores que mudam, como um nome ou uma contagem, em data-v como um objeto JSON e faça referência a eles como $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 traduz o texto em torno dos valores uma vez, como Hi {0}, you have {1} new messages, e coloca os valores de volta na página. A tradução é armazenada em cache e funciona para cada nome e cada contagem, e os valores em si nunca são enviados para Magic Translate.

Para mostrar novos valores, altere data-v. A tradução em cache é reutilizada e nenhuma solicitação é feita:

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

Os valores são numerados na ordem em que aparecem pela primeira vez. A tradução pode movê-los para onde o idioma precisar deles, por exemplo, {1} neue Nachrichten für {0}.

Algumas regras:

  • Somente as teclas de data-v são substituídas, então textos como $5 permanecem como estão. Se duas teclas começarem da mesma forma, como count e counts, a mais longa vence.
  • O mesmo nome pode aparecer mais de uma vez.
  • Os valores são inseridos como texto, nunca como HTML. Em vez disso, coloque marcação no texto ao redor deles: Hi <b>$name</b>.
  • No conteúdo, as variáveis são substituídas somente no texto, não em atributos como href ou title.
  • Se data-v não for um objeto JSON válido, o texto não será traduzido e um aviso será registrado. Uma chave que não aparece no texto também registra um aviso.
  • $name fica visível até que o script seja carregado. Carregue o script no início da página ou oculte esses elementos até lá.

Opções

Use esses atributos para definir opções para um único elemento:

AtributoValorDescrição
data-formalityinformal ou formalDefine a formalidade da tradução.
data-langum código de idiomaSubstitui o idioma da página.
data-t-iduma identificaçãoPermite que você edite esse uso do texto sozinho. Ela se aplica ao conteúdo do elemento, não ao seu data-t-attrs.
<t data-lang="fr" data-formality="formal">How are you?</t>

Conteúdo que muda

O conteúdo adicionado à página posteriormente, ou alterado por seus scripts, também é traduzido. Isso funciona para conteúdo renderizado por JavaScript, por exemplo, com htmx ou jQuery.

Todas as traduções solicitadas ao mesmo tempo são enviadas para a API em uma única solicitação, e as traduções são armazenadas em cache. Você pode marcar quantos elementos quiser.

Limitações

O conteúdo de um único elemento não pode exceder 10 KB, o que equivale a cerca de 5.000 caracteres. Os elementos aninhados são traduzidos como parte do elemento <t> principal.

AnteriorJavaScriptPróximoAPI JavaScript