Leitura Bilíngue (Bilingual Reading)
Visão Geral
Transforma um PDF técnico em inglês em uma versão HTML offline com parágrafos lado a lado em chinês e inglês: cada capítulo é um arquivo HTML autocontido (UTF-8, imagens embutidas em base64, arquivo único que pode ser aberto offline), com um índice recolhível fixo à esquerda e um botão flutuante 🌐 no canto inferior direito que alterna entre os modos 'apenas inglês', 'apenas chinês' e 'chinês-inglês', mantendo a seleção após a navegação entre páginas.
Gatilho e Entrada
- Entrada: PDF em inglês (caminho local ou URL; primeiro baixar para o computador).
- Saída:
index.html+ página de abertura/fechamento +chapter-NN.html(um arquivo por capítulo), empacotados em um zip final. - Se o PDF tiver marcadores (
get_toc()), a estrutura de capítulos será baseada neles e confirmada com o usuário antes de prosseguir; se o usuário confirmar 'não dividir', a produção será em lote.
Regras Principais (Não Violáveis)
- O texto original deve ser traduzido parágrafo por parágrafo na íntegra, sem resumos ou fusões.
- Um arquivo por capítulo, sem dividir capítulos; dentro do capítulo, os parágrafos seguem a ordem das páginas do livro original.
- Blocos de código (
<pre><code>) permanecem em inglês, sem tradução; códigos com chaves não devem ser escritos dentro de f-strings. - Parágrafos em chinês têm fundo azul claro + uma barra lateral esquerda de 4px para diferenciá-los dos parágrafos em inglês; itens de lista em chinês seguem o mesmo estilo.
- Imagens são comprimidas e embutidas em base64; após cada página do livro original ser totalmente traduzida, uma marca de página separada é adicionada (
page_mark(pdf_page)) exibindo o número da página original do PDF. - Nomes de arquivo em minúsculas com hífen (
chapter-01.html,front-matter.html). - As entradas do índice são geradas com base na hierarquia dos marcadores (l2/l3); links entre capítulos são interconectados, e os capítulos inicial e final ficam desabilitados.
Fluxo de Trabalho Geral
① Definir intervalo de páginas → ② Extrair texto → ③ Extrair imagens → ④ Comprimir e converter para base64
→ ⑤ Ler texto original e traduzir → ⑥ Escrever script de construção build_chN.py → ⑦ Corrigir chaves → ⑧ Executar e gerar
→ ⑨ Conectar navegação → Validar → Entregar
Primeiro, criar um capítulo de amostra (geralmente ch1) para o usuário aprovar o estilo; após aprovação, consolidar/reutilizar book_theme.py e produzir em lote contínuo, sem necessidade de novas confirmações intermediárias. As páginas de abertura/fechamento e o index.html são finalizados por último.
Etapas Detalhadas
① Definir Intervalo de Páginas
Entrada: TOC completo / números de capítulo. Usar PyMuPDF para ler os marcadores:
import fitz
doc = fitz.open("book.pdf")
toc = doc.get_toc() # [[level, title, page_1based], ...]
Converter páginas baseadas em 1 para intervalo baseado em 0 do PyMuPDF. As páginas dos marcadores frequentemente têm deslocamento em relação às páginas físicas; usar os marcadores como referência; listar a divisão de capítulos para o usuário e confirmar antes de começar.
② Extrair Texto
text = "".join(doc[p].get_text("text", sort=True) for p in range(start0, end0+1))
open("chN_raw.txt", "w", encoding="utf-8").write(text)
sort=True garante a ordem de leitura, sem confusão em layouts de múltiplas colunas. Escrever o texto original em chN_raw.txt para cada capítulo.
③ Extrair Imagens
Usar scripts/extract_assets.py:
python3 extract_assets.py book.pdf <start_page_1based> <end_page_1based> --out assets
page.get_images(full=True)→ deduplicar por xref →extract_image(xref).- jpx (JPEG2000), RGBA, modo P: converter para RGB antes de salvar como JPEG (compatível com navegadores).
④ Comprimir e Converter para base64
Feito junto com o passo anterior (embutido no script): abrir com PIL; se largura >800px, redimensionar proporcionalmente para 800 (LANCZOS); JPEG q≈68; escrever base64 em assets/figN-M.txt. Cada imagem comprimida para 30–80 KB.
⑤ Ler Texto Original e Traduzir
- Ler
chN_raw.txtem segmentos (500–600 linhas por vez), traduzir parágrafo por parágrafo, registrando anotações correspondentes às legendas das figuras (por exemplo, diagrama de corvo → texto "notas"). - Segmentos de código: pular tradução; tabelas: converter para HTML table; listas: traduzir item por item, sem mesclar.
⑥ Escrever Script de Construção
build_chN.py deve começar com from book_theme import P, LI, CODE, INLINE, H, img_b64, page_mark, page; o corpo é escrito na f-string body. Dentro da f-string, P()/LI() devem ser escritos como {P(...)} para serem avaliados; blocos de código são extraídos como variáveis string comuns CODE_X = '''...''' e concatenados com + CODE_X. Modelo completo no docstring do cabeçalho de scripts/book_theme.py.
⑦ Pós-processamento: Corrigir Chaves
python3 scripts/fix_braces.py build_chN.py
Percorrer linhas: linhas começando com P('/LI(' recebem { no início; encontrar a primeira linha que termina com ) e adicionar } no final. Não processar chamadas de img_b64(/page( para evitar adicionar } erroneamente no final de linhas page().
⑧ Executar e Gerar
python3 build_chN.py # O script imprime o nome do arquivo e o tamanho em KB se bem-sucedido
⑨ Conectar Navegação
Preencher prev/next com base nos números de capítulo (ch1 prev=front-matter.html, último capítulo next=None); capítulos inicial e final usam placeholder disabled (já tratado em page()).
Finalização
front-matter.html,closing.html(com ou sem bibliografia recomendada, conforme combinado com o usuário),index.htmlcomo entrada principal (links para todos os capítulos).- Empacotar com
python3 -m zipfile -c bilingual_reading.zip *.htmle entregar o zip.
Branches e Tratamento de Exceções
| Condição | Tratamento |
|---|---|
| Imagem no modo jpx / RGBA / P | extract_assets.py converte para RGB antes de salvar como JPEG |
| Código com chaves (dict JSON) dentro de f-string | Não escrever na f-string; extrair como CODE_X = '''...''' e concatenar com + CODE_X |
{<P( escrito incorretamente | Corrigir com sed 's/{<P(/{P(/g' |
Adição em lote de } no final de linhas page() | fix_braces.py já evita; se ainda ocorrer, remover manualmente o } extra no final da linha |
| Usuário pede 'ver o resultado antes de continuar' | Fazer apenas o capítulo de amostra, pausar e aguardar feedback |
| Usuário pede 'não traduzir código' | Todos os <pre><code> permanecem em inglês (padrão já é assim) |
| Mais itens de depuração | Ver references/troubleshooting.md |
Índice de Recursos
scripts/book_theme.py— Módulo compartilhado principal: CSS/JS/esqueleto da página + funções P, LI, CODE, INLINE, H, img_b64, page_mark, page. Para alterar o estilo, modificar apenas este arquivo.scripts/extract_assets.py— Etapas ③④: extrair imagens, comprimir, converter para base64 e escrever em assets/.scripts/fix_braces.py— Etapa ⑦: corrigir chaves de f-strings em lote.references/style-guide.md— Detalhes de estilo e interação (cores, layout, componentes, verificação de conformidade).references/troubleshooting.md— Tabela de resolução de problemas e experiência reutilizável.
Checklist de Validação
- Estilo do capítulo de amostra aprovado pelo usuário (fundo azul claro para chinês, itens de lista em chinês no mesmo estilo, marca de página presente)
- Texto original traduzido parágrafo por parágrafo na íntegra; blocos de código não traduzidos; imagens embutidas em base64 e funcionando offline
- Cada HTML de capítulo pode ser aberto independentemente; índice recolhível; âncoras funcionando
- Botão 🌐 com três estados de alternância; seleção mantida entre páginas (localStorage)
- Links entre capítulos corretamente interconectados; botões de capítulos inicial e final desabilitados
- Todos os arquivos em UTF-8; nomes em minúsculas com hífen; empacotados em zip para entrega