ESPDocs/CHANGELOG.md

Registro de mudanças

Tudo o que muda de relevante no ESPDocs está aqui. O formato segue o Keep a Changelog e o projeto segue o Versionamento Semântico.

Não lançado

1.6.0 - 2026-11-02

Adicionado

• Chinês simplificado (/zh-CN), o sexto idioma do site, com o mesmo conteúdo dos demais, menos o livro (/zh-CN/livro responde 404):
  • Interface, séries, frameworks, diagramas de pinos, glossário, diagnóstico, componentes e exemplos de código com comentários em chinês (mensagens de log dos exemplos ficam em inglês, para não aparecerem quebradas no monitor serial).
  • Busca em chinês: o motor entende consultas como s3 闪存, c6 usb 引脚 ou 哪款 esp32 有 psram, segmentando o texto com Intl.Segmenter.
  • SEO próprio (hreflang, sitemap, JSON-LD em zh-CN) e negociação da raiz: Accept-Language com zh, zh-Hans ou zh-TW leva a /zh-CN.
  • O filtro alfabético A–Z do glossário não aparece em chinês.
• scripts/verifica-busca.mjs, chamado pelo teste de fumaça: roda o motor de busca sobre o índice de cada idioma e confere que as respostas e os links estão no idioma da página.
• check-i18n passa a procurar português dentro dos dados dos outros idiomas.

Corrigido

• Na busca, as respostas diretas (por exemplo "Flash no ESP32-S3", "Dados da série", "Pinos do ESP32-S3 ligados à memória flash") saíam em português em inglês, espanhol, francês e alemão, e levavam a /series/... em vez do idioma da página. Agora textos e links seguem o idioma.
• Em francês e alemão, valores de ADC, SPI, toque capacitivo, consumo e outros ainda estavam em português (por exemplo "até 18 canais", "conforme a carga"); em espanhol, dois valores de consumo. Todos traduzidos.
• O seletor de chip reconhecia "Sim"/"Yes" para Matter, Arduino e segurança, mas não "Sí", "Oui" nem "Ja"; agora reconhece os seis idiomas.
• A home em alemão mostrava "14 frameworks" em minúscula.

1.5.0 - 2026-11-02

Adicionado

• Internacionalização completa para os idiomas Francês (fr) e Alemão (de) (Fase 5):
  • Ativação do francês e do alemão em ENABLED_LOCALES = ["pt", "en", "es", "fr", "de"] e no seletor de idiomas do cabeçalho.
  • Tradução técnica integral e paridade estrutural em messages/fr.json e messages/de.json (15 namespaces), nos arquivos de dados em data/{fr,de}/ (series.json, frameworks.json, conexoes/*.json) e lib/data/{fr,de}/ (glossario.js, diagnostico.js, componentes.js, topicos.js).
  • Tradução técnica natural com tratamento formal respeitado: "vous" em francês e "Sie" em alemão.
  • 14 exemplos práticos de código com comentários em francês e 14 em alemão em public/exemplos/{fr,de}/.
  • Slugs canônicos ASCII por idioma:
    • Francês: /fr/series, /fr/catalogue, /fr/comparaison, /fr/composants, /fr/diagnostic, /fr/frameworks, /fr/glossaire, /fr/selecteur, /fr/a-propos.
    • Alemão: /de/serien, /de/katalog, /de/vergleich, /de/komponenten, /de/diagnose, /de/frameworks, /de/glossar, /de/auswahl, /de/ueber-uns.
  • Busca dedicada por idioma em /api/busca/fr e /api/busca/de com normalização de acentos, caracteres alemães (ä, ö, ü, ß) e ligaduras francesas (œ, æ), sem menção ao livro e com links diretos aos slugs canônicos.
  • Exclusão total e estrita de referências ao livro fora do português, com /fr/livro e /de/livro respondendo HTTP 404 estrito.
  • Tabela do catálogo de placas com colunas traduzidas e mapeamento de valores técnicos nos idiomas francês e alemão.
  • Negociação de idioma na raiz com roteamento para fr ou de com base nos cabeçalhos Accept-Language ou cookies NEXT_LOCALE=fr / NEXT_LOCALE=de, e fallback padrão para en para navegadores com o idioma inativo restante (zh-CN).
  • Metadados de SEO, Open Graph e Twitter Cards localizados com og:locale (fr_FR, de_DE), inLanguage (fr, de) e hreflang cruzado entre pt-BR, en, es-419, fr-FR, de-DE e x-default.
  • Suporte CSS com hifenação automática (hyphens: auto) para alemão e francês via atributo lang dinâmico no layout raiz.
  • Extensão da suíte de verificação: scripts/check-i18n.mjs valida fr e de, scripts/smoke-imagem.sh testa as rotas francesas e alemãs e scripts/verifica-vazamentos.py varre todas as 36 rotas em francês e 36 em alemão (texto visível e blocos JSON-LD).

Corrigido

• O cabeçalho passou a caber em telas estreitas. Desde o seletor de idioma, a faixa de ícones ficava com ~410 px de largura mínima e o botão do menu era cortado em celulares (390 e 360 px). Agora o seletor fica compacto no celular e o logo mostra só o ícone abaixo de 360 px; sem rolagem horizontal de 320 px para cima.

1.4.2 - 2026-11-02

Corrigido

• A release passa os segredos ao workflow de CI que chama (secrets: inherit). Sem isso, uma release que precisava construir a imagem falhava no login do registro.
• Inclui a correção da 1.4.1: a tag v1.4.1 não chegou a ter release, porque a CI dela falhou pelo problema acima.

1.4.1 - 2026-11-01

Corrigido

• As fotos das placas de desenvolvimento oficiais na página de cada série foram feitas para fundo claro e ficavam ruins no tema escuro. O quadro delas agora é sempre branco, nos dois temas; o resto do site continua seguindo o tema.

1.4.0 - 2026-11-01

Adicionado

• Internacionalização completa para o idioma espanhol neutro latino-americano (es) (Fase 4):
  • Ativação do espanhol em ENABLED_LOCALES = ["pt", "en", "es"] e no seletor de idiomas do cabeçalho.
  • Tradução técnica integral e paridade estrutural em messages/es.json (15 namespaces) e arquivos de dados em data/es/ (series.json, frameworks.json, conexoes/*.json) e lib/data/es/ (glossario.js, diagnostico.js, componentes.js, topicos.js).
  • 14 exemplos práticos de código com comentários em espanhol em public/exemplos/es/.
  • Roteamento com slugs canônicos em espanhol (/es/catalogo, /es/comparacion, /es/componentes, /es/diagnostico, /es/frameworks, /es/glosario, /es/selector, /es/acerca).
  • Busca por idioma em /api/busca/es com normalização de acentos e 'ñ', sem menção ao livro e com links para os slugs canônicos em espanhol.
  • Exclusão total e estrita de referências ao livro no idioma espanhol (menu, rodapé, busca, sitemap e metadados), mantendo /es/livro respondendo HTTP 404.
  • Tabela de catálogo com cabeçalhos traduzidos e mapeamento de valores na interface em espanhol.
  • Negociação de idioma na raiz com roteamento para es para cabeçalhos Accept-Language es-* ou cookie NEXT_LOCALE=es, e fallback padrão para en para navegadores com idiomas inativos (fr, de, zh-CN).
  • Metadados de SEO, Open Graph e Twitter Cards localizados com og:locale (es_419), inLanguage (es-419) e hreflang cruzado entre pt-BR, en, es-419 e x-default.
  • Extensão dos scripts de verificação: scripts/check-i18n.mjs valida es, scripts/smoke-imagem.sh testa as rotas espanholas e scripts/verifica-vazamentos.py varre as 36 rotas em espanhol (texto visível e JSON-LD).

1.3.0 - 2026-11-01

Adicionado

• Internacionalização completa para o idioma inglês (en) (Fase 3):
  • Ativação do inglês em ENABLED_LOCALES = ["pt", "en"] com reexibição do seletor de idiomas no cabeçalho.
  • Tradução técnica integral e paridade estrutural em messages/en.json (15 namespaces) e arquivos de dados em data/en/ (series.json, frameworks.json, conexoes/*.json) e lib/data/en/ (glossario.js, diagnostico.js, componentes.js, topicos.js).
  • 14 exemplos práticos de código com comentários em inglês em public/exemplos/en/.
  • Roteamento com slugs canônicos em inglês (/en/catalog, /en/compare, /en/components, /en/diagnostics, /en/frameworks, /en/glossary, /en/selector, /en/about).
  • Índice de busca dedicado por idioma em /api/busca/[locale], com links direcionando aos slugs do idioma correspondente e caixa de busca localizada.
  • Exclusão total e estrita de referências ao livro no idioma inglês (menu, rodapé, busca, sitemap e metadados), mantendo /en/livro respondendo HTTP 404.
  • Tabela de catálogo com cabeçalhos traduzidos e mapeamento de valores na interface inglesa.
  • Negociação de idioma na raiz com fallback padrão para en para navegadores com idiomas inativos ou genéricos, e redirecionamento 307 de prefixos inativos (es, fr, de, zh-CN) para /en preservando o mapeamento de slugs.
  • Metadados de SEO, Open Graph e Twitter Cards localizados, com hreflang cruzado entre pt-BR, en e x-default.
• Verificações permanentes contra vazamento de português no inglês: scripts/check-i18n.mjs falha em textos idênticos entre pt e en (fora de uma lista de termos técnicos), e scripts/verifica-vazamentos.py, chamado pelo teste de fumaça da CI, varre as 36 rotas em inglês, texto visível e JSON-LD.

Alterado

• A raiz / passa a levar quem não fala português ao inglês (/en); o português continua em /pt. Idiomas ainda sem tradução (es, fr, de, zh-CN) redirecionam para /en.

1.2.0 - 2026-11-01

Adicionado

• Infraestrutura de internacionalização com next-intl (Fase 1):
  • Roteamento com prefixo de idioma sob app/[locale]/, com 6 locales declarados (pt, en, es, fr, de, zh-CN).
  • middleware.js com negociação de idioma na raiz por cookie NEXT_LOCALE e cabeçalho Accept-Language (com pesos q), redirecionamento 308 de URLs antigas sem prefixo para /pt/, e retorno 404 para /livro fora do português.
  • Seletor de idiomas acessível no cabeçalho com atalho para os 6 idiomas, persistência via cookie NEXT_LOCALE e mapeamento de rota correspondente.
  • Regras de tipografia de sistema CJK para zh-CN e hifenização/quebra de palavras para de e fr.
• Extração de strings e dados canônicos (Fase 2):
  • Catálogo de mensagens canônico messages/pt.json cobrindo 15 namespaces de páginas e componentes sem alteração de conteúdo.
  • Conjunto de dados canônicos em data/pt/ (series.json, frameworks.json, conexoes/*.json) e módulos em lib/data/pt/ (glossario.js, diagnostico.js, componentes.js, topicos.js) com carregadores por locale em lib/data/index.js.
  • Script automatizado de validação check:i18n integrado ao npm run check, verificando paridade de chaves, ausência de valores vazios e garantia estrita de ausência de referências ao livro fora do português.
• Controle de idiomas ativos e proteção contra conteúdo não traduzido:
  • Configuração centralizada em i18n/links.js (ENABLED_LOCALES), atualmente restrita a ["pt"].
  • Redirecionamento 307 de qualquer prefixo de idioma inativo para /pt preservando o caminho ou mapeamento equivalente.
  • Negociação de idioma na raiz selecionando unicamente entre os idiomas ativos (com fallback em pt).
  • Seletor de idiomas no cabeçalho oculto enquanto apenas um idioma estiver ativo.
  • Sitemap, hreflang/alternates e build SSG restritos aos idiomas ativos.

Alterado

• Todas as páginas passam a viver sob /pt/ (por exemplo /pt/series). As URLs antigas, sem prefixo, redirecionam com 308 para o endereço novo, e a raiz / redireciona para o idioma negociado. O conteúdo do site em português não mudou.
• O teste de subida da imagem na CI virou scripts/smoke-imagem.sh: confere as rotas de cada idioma, a negociação de Accept-Language, os redirects 308 das URLs antigas, o 404 do livro fora do português e a metadata no <head>, e falha se o servidor registrar erro de render. O curl só na raiz deixou passar uma home quebrada.
• A metadata (título, canonical, Open Graph) sempre sai no <head> do HTML inicial, para qualquer cliente, como já era antes do i18n.
• A raiz / redireciona direto para /<idioma>, em um salto só.

1.1.0 - 2026-11-01

Adicionado

• Busca no site, aberta pelo botão do cabeçalho ou por Ctrl/⌘+K. O índice (séries, frameworks, glossário, erros de diagnóstico, componentes e conexões) é gerado no build, em /api/busca.

Alterado

• Os links do repositório do projeto (rodapé, "Sobre", dados estruturados) apontam para o Gitea, e o ícone do GitHub virou o do Gitea. Os links dos frameworks da Espressif continuam no GitHub, porque os repositórios são deles.
• O site passou a rodar na Oracle, a partir da imagem Docker do registro do Gitea, em espdocs.cienciaembarcada.com.br e espdocs.lucasrguerra.dev.br.
• CI: a imagem é construída, escaneada e testada uma vez, em arm64, no push da branch, e o release só aplica as tags; o gatilho pull_request (que repetia o push) e o segundo next build do job de lint saíram, e os caches do npm e da compilação do Next ficam entre as execuções.

1.0.0 - 2026-10-30

A primeira versão com tag. O trabalho anterior nunca foi tagueado, então esta entrada resume tudo desde o primeiro commit, em 2025-10-21, até a imagem Docker.

Conteúdo

• Documentação não oficial do ecossistema ESP32 em português: uma página por série de chips, com especificações, conexões e consumo, e a página de comparação lado a lado.
• Diagramas interativos de conexões e componentes, com o esquema de dados de conexões padronizado.
• Frameworks documentados: ESP-IDF, Arduino, MicroPython, ESP-RainMaker e ESP-Matter.
• Glossário técnico, página "Sobre" e chamadas para o catálogo.
• Catálogo de placas de desenvolvimento a partir de uma planilha do Google (/api/placas), com filtros e cache de 10 minutos.
• Ferramenta de seleção: perguntas sobre o projeto (Ethernet, tela e outras) e recomendação da série mais adequada.
• Novos modelos, incluindo o ESP32-H4, e a contagem de componentes e de drivers (interface, conectividade e áudio) ampliada.

Interface e acessibilidade

• Tema escuro e redesenho das páginas internas no novo sistema de design, com contraste AAA e auditoria automática de temas e de páginas (npm run check).
• Identidade nova: logo, ícones, manifest e imagens Open Graph.
• SEO: mapa do site, dados estruturados, trilhas de navegação e favicons.
• Exportação do conteúdo em PDF CMYK e dos slides de treinamento em PDF 16:9, gerados com Puppeteer (scripts locais).

Dados corrigidos

• Revisão dos dados das séries contra os datasheets oficiais da Espressif: consumo, temperatura, ADC, PSRAM, memória LP, CAN FD, frequências e versões de Secure Boot do ESP32, S2, S3, C2, C3, C5, C6, C61, H2, H4, P4 e S31.

Implantação

• Imagem Docker (node:22-alpine, build standalone, usuário sem privilégio, HEALTHCHECK), pronta para o servidor Oracle, publicada para linux/arm64 em git.lucasrguerra.dev.br/lucasrguerra/espdocs. A variável NEXT_OUTPUT=standalone liga o empacotamento só dentro da imagem; fora dela o build continua o mesmo para o pm2 (start.config.js, porta 3001).
• O código passou para o Gitea, com CI em .gitea/workflows: lint, auditorias, Trivy no repositório e na imagem, e teste de que a imagem sobe e responde. O Release reaproveita a imagem quando nada do que a compõe mudou.

Segurança

• next 15.5.28, que corrige a execução remota de código sem autenticação na otimização de imagens (GHSA-2464-fhr4-w9xw), e postcss fixado acima da cópia embutida no next.