HTML

Traduza textos e atributos HTML, preservando as partes não alteradas do código-fonte e definindo o idioma do documento como o idioma de destino.

O HTML organiza texto legível em uma estrutura que também contém links, comportamentos e informações de acessibilidade. O processador html seleciona os trechos de texto e atributos descritivos compatíveis e insere suas traduções no código-fonte original para um único idioma de destino. Ele não divide uma página multilíngue em regiões separadas por idioma.

Preserve a estrutura do documento de entrada #

Os documentos mantêm o doctype original e os elementos explícitos. Fragmentos continuam sendo fragmentos: a tradução não adiciona elementos <html>, <head> ou <body> ao redor deles. Comentários, atributos não alterados, tipos de aspas e espaços em branco fora dos trechos traduzidos permanecem como no código-fonte.

Quando há um elemento <html> explícito, seu valor de lang é substituído pelo idioma de destino. Se ele não tiver esse atributo, recebe um atributo lang. Por exemplo, <html lang="en"> se torna <html lang="fr"> para o francês. Um fragmento sem um elemento <html> explícito não recebe esse elemento apenas para indicar o idioma.

Por exemplo, este fragmento contém texto visível e texto de acessibilidade:

html
<section>
  <h2>Delivery options</h2>
  <p>Read the <a href="/delivery">delivery policy</a>.</p>
  <img src="/truck.svg" alt="Delivery truck" />
  <input placeholder="Enter your address" aria-label="Delivery address" />
</section>

O título, o parágrafo, o rótulo do link, o texto alternativo da imagem, o texto de exemplo do campo de entrada e o rótulo ARIA são textos compatíveis com a tradução. O destino do link e a origem da imagem continuam sendo propriedades estruturais. Traduzir esse fragmento não cria links localizados nem substitui arquivos de imagem.

Seleção de atributos e regiões #

Os atributos nativos compatíveis incluem alt e title em imagens, placeholder e title em campos de entrada e áreas de texto, determinados atributos title, content de elementos meta e atributos de rótulo ARIA. Revise os metadados com cuidado: selecionar um atributo pelo nome não garante que todos os seus valores sejam texto em linguagem natural. As regras configuradas para propriedades de componentes podem adicionar atributos para elementos identificados pelo nome.

O conteúdo de elementos de script, estilo, código pré-formatado, código, matemática, template, noscript e textarea fica fora da extração padrão de texto. Um elemento ignorado ainda pode ter um atributo descritivo compatível. Para SVG, há uma seleção específica dos conteúdos title, desc e text compatíveis, em vez de traduzir dados de desenho arbitrários.

A marcação em linha e os tokens {{...}} são protegidos por marcadores durante a tradução do texto. Na reconstrução, eles são restaurados nos trechos traduzidos. Verifique a estrutura de elementos do resultado e renderize suas variáveis com valores representativos da aplicação.

Reutilização e saída com preservação do código-fonte #

Para permitir a reutilização, o texto de origem e a tradução anteriores precisam ter estruturas de texto e marcadores correspondentes. O processador verifica esse alinhamento e pode rejeitar um par ambíguo. Mantenha a tradução aceita associada à respectiva revisão do texto de origem, em vez de comparar páginas renderizadas sem relação entre si.

Apenas os trechos traduzidos e o atributo de idioma do elemento <html> explícito são alterados; as partes não alteradas do código-fonte são copiadas diretamente para o resultado. O processador não sanitiza HTML de fontes não confiáveis. Mantenha as verificações de segurança e renderização da sua aplicação.

Se um aninhamento incorreto fizer o analisador combinar textos de marcações sem relação entre si, o processador rejeitará o documento em vez de gerar uma tradução ambígua. Corrija o aninhamento e tente novamente. Quando a omissão de tags HTML é válida, não é necessário adicionar uma estrutura de documento.

Configure arquivos HTML na CLI ou no GitHub App #

A CLI e o GitHub App inferem html a partir de .html e .htm. Selecione os arquivos de origem em .lingo/config.json, mantendo os arquivos de destino gerados fora dos padrões de seleção dos arquivos de origem:

json
{
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    { "pattern": "pages/en/**/*.html", "format": "html" },
    { "pattern": "pages/en/**/*.htm", "format": "html" }
  ]
}

O format explícito é opcional para essas extensões. Vincule o projeto à sua organização e ao seu engine de localização usando a configuração da CLI ou informe o engine para o GitHub App. Cada destino é um arquivo de idioma separado, como pages/fr/index.html. O HTML não oferece suporte à tradução por chave.

Depois de obter o resultado, renderize o documento ou fragmento na aplicação que o utiliza. Compare os links e os atributos não textuais e confira o texto de acessibilidade junto com o texto visível. Se o HTML vier de um CMS, siga as instruções desse conector para selecionar campos e gravar os resultados de volta; os conectores podem aceitar entradas diferentes, mesmo quando o processamento de HTML faz parte da implementação.