Aula Completa: Tradução Multilíngue de HTML

Guia completo (iniciante ao avançado) para traduzir páginas PT/EN/ES sem quebrar estrutura, scripts, links e experiência do usuário.

🏠 Capa 📘 Módulo 1 🎓 Módulo 2

0) Trilha por nível de experiência

👶 Leigo

Foque nas seções 1, 2 e 6.
Use o prompt pronto sem alterar estrutura técnica.
Valide com o checklist final da seção 7.

🛠️ Intermediário

Siga as seções 1 a 7 completas.
Adapte termos com base no glossário.
Faça revisão funcional e visual antes do deploy.

🚀 Avançado

Padronize este fluxo como processo de equipe.
Inclua critérios de qualidade e acessibilidade.
Mantenha consistência terminológica entre projetos.

1) Visão geral da metodologia

Objetivo técnico

Traduzir texto visível mantendo 100% da estrutura original.
Preservar comportamento de tabs, gráficos, dark mode e navegação.
Entregar versões consistentes PT/EN/ES com links corretos.

Resultado esperado

`arquivo.html` (PT)
`arquivo.en.html` (EN)
`arquivo.es.html` (ES)
Checklist de validação técnica e textual.

2) O que traduzir vs. o que não traduzir

Traduzir	Não traduzir
Textos visíveis (H1-H6, parágrafos, listas). Botões e labels. `title`, `meta description`, `aria-label`, `alt` (quando textual). Mensagens exibidas ao usuário em JS.	Classes CSS, IDs, data-attributes estruturais. Nomes de funções/variáveis JS. Paths de assets e dados (GeoJSON, CSV, scripts). Lógica de eventos, inicialização de gráficos e comportamento visual.

3) Passo a passo completo (workflow profissional)

Criar backup do original: `arquivo.original.html`.
Mapear blocos traduzíveis: header, botões, tabs, conteúdo, footer e mensagens de UI.
Traduzir PT → EN mantendo estrutura idêntica.
Duplicar EN → ES para garantir consistência estrutural entre versões.
Revisar links multilíngues no seletor de idioma (`.html`, `.en.html`, `.es.html`).
Validar JS/UI (tabs, tema, gráficos, dropdowns).
Validar UTF-8 e caracteres especiais.
Sincronizar ambientes (ex.: `olokun/`, `site/`, `gh-pages-temp/`).
Commit e deploy com mensagem clara.

4) Prompt avançado (versão aula completa)

Tarefa: Traduzir um arquivo HTML para PT/EN/ES sem alterar estrutura técnica.

Contexto:
- Arquivo fonte: [NOME_DO_ARQUIVO].html
- Versões de saída: .html (PT), .en.html (EN), .es.html (ES)
- Ambiente usa UI com tabs, tema claro/escuro, links e scripts JavaScript.

Regras obrigatórias:
1) Preservar DOM 100% (mesmas tags, classes, ids, atributos e ordem).
2) Traduzir apenas textos de interface e metadados textuais.
3) Não alterar nomes de funções, variáveis, paths de assets e dados.
4) Manter funcionamento de tabs, gráficos, dropdowns e dark mode.
5) Corrigir e preservar codificação UTF-8 (sem caracteres corrompidos).
6) Garantir links de idioma corretos:
   - arquivo.html
   - arquivo.en.html
   - arquivo.es.html
7) Usar terminologia consistente:
   PT: Idioma | Tema | Dashboard | Ver Mapa | Mapa de Resultados
   EN: Language | Theme | Dashboard | View Map | Results Map
   ES: Idioma | Tema | Panel de Control | Ver Mapa | Mapa de Resultados

Etapas de execução:
A) Ler e identificar todos os nós de texto traduzíveis.
B) Gerar EN preservando estrutura.
C) Gerar ES preservando estrutura.
D) Revisar links cruzados de idioma.
E) Revisar strings de botões, labels, alt/aria e metas.
F) Rodar checklist final.

Checklist final obrigatório:
[ ] Estrutura HTML preservada
[ ] JS intacto
[ ] Links multilíngues corretos
[ ] UTF-8 válido
[ ] Terminologia consistente
[ ] Funcionalidades visuais intactas (tabs, tema, gráficos)

Saída esperada:
- Arquivos finais PT/EN/ES + breve relatório de validação.

5) Exemplos práticos (antes/depois)

Exemplo 1 — Botão

<button>Ver Mapa</button>
EN: <button>View Map</button>
ES: <button>Ver Mapa</button>

Exemplo 2 — Meta Description

<meta name="description" content="...">
✔ Traduzir apenas o texto do content
✘ Não alterar name ou estrutura da tag

6) Erros comuns e como evitar

Erro crítico

Traduzir classe/ID: quebra CSS/JS. Solução: nunca traduzir identificadores técnicos.

Erro frequente

Links de idioma errados: idioma troca para página incorreta. Solução: revisar trio `.html/.en.html/.es.html` em todas as versões.

Erro frequente

Codificação corrompida: acentos quebrados. Solução: salvar em UTF-8 e validar visualmente títulos e textos longos.

Boa prática

Backup original: manter `arquivo.original.html` antes de iniciar qualquer tradução.

7) Checklist de homologação (produção)

✅ Abrir as três versões no navegador e validar textos.
✅ Testar tema claro/escuro e persistência.
✅ Testar tabs/accordions/charts (sem console errors).
✅ Validar responsividade em desktop e mobile.
✅ Revisar ortografia EN/ES com leitura final.
✅ Conferir deploy e branch correta antes do push.

8) Glossário completo (didático)

Termo	Definição para leigos	Uso técnico (intermediário/avançado)
DOM	Esqueleto da página HTML.	Estrutura de nós/elementos que scripts e estilos usam.
UTF-8	Formato que evita acentos quebrados.	Codificação padrão para internacionalização de conteúdo.
Acessibilidade	Facilidade de uso por todas as pessoas.	Uso de `aria-label`, contraste e semântica adequada.
Deploy	Publicar a versão no site.	Envio para branch de produção e validação pós-publicação.
Homologação	Conferência final antes de considerar pronto.	Checklist funcional, visual e técnico com aceite.
Regressão	Algo que funcionava e parou de funcionar.	Quebra após alteração; exige teste de não-regressão.