DEV Community

Cover image for Por Que Sua Tabela Exportada Tem Caracteres Estranhos (E Como Corrigir)
circobit
circobit

Posted on

Por Que Sua Tabela Exportada Tem Caracteres Estranhos (E Como Corrigir)

#webdev #python #beginners #tutorial

Você exporta uma tabela. Abre o CSV. Em vez de "José" vê "José". Em vez de "€" vê "€". Em vez de um travessão vê "â€"".

Bem-vindo ao inferno do encoding.

Este guia explica por que isso acontece e como corrigir — seja exportando manualmente ou construindo ferramentas de extração.

O Que Está Realmente Acontecendo

Codificação de caracteres é como computadores representam texto como bytes. Diferentes codificações usam padrões de bytes diferentes para o mesmo caractere.

O culpado mais comum: UTF-8 interpretado como Latin-1 (ou vice-versa).

UTF-8 usa múltiplos bytes para caracteres não-ASCII. Quando um software lê esses bytes como Latin-1 (codificação de byte único), cada byte se torna um caractere ilegível separado.

Caractere Bytes UTF-8 Lido como Latin-1
é C3 A9 é
€ E2 82 AC €
— E2 80 94 â€"
ñ C3 B1 ñ
ã C3 A3 ã
ç C3 A7 ç

O padrão é consistente: sequências de múltiplos bytes se tornam múltiplos caracteres errados.

Onde o Encoding Quebra

1. A Página de Origem

O site pode declarar uma codificação mas servir outra. Ou não declarar nada, deixando os navegadores adivinharem.

<!-- Declara UTF-8 -->
<meta charset="UTF-8">

<!-- Mas o servidor envia -->
Content-Type: text/html; charset=ISO-8859-1
Enter fullscreen mode Exit fullscreen mode

Quando declarações conflitam, navegadores geralmente acertam. Ferramentas de exportação podem não acertar.

2. O Processo de Exportação

Se sua ferramenta de extração não preserva a codificação, bytes são reinterpretados.

O textContent do JavaScript retorna strings Unicode, o que é seguro. Mas converter para um arquivo requer escolher uma codificação. Se essa escolha estiver errada, a corrupção acontece.

3. A Aplicação que Abre o Arquivo

Você exporta um CSV UTF-8 válido. O Excel abre como Latin-1 porque adivinhou errado. Mesma corrupção, causa diferente.

Por isso o mesmo arquivo fica normal em uma aplicação e quebrado em outra.

Como Diagnosticar o Problema

Reconhecimento de Padrões

Certas corrupções são diagnósticas:

Você vê Original era
á, é, í, ó, ú á, é, í, ó, ú (acentos)
ã, õ ã, õ (til)
ç ç (cedilha)
ä, ö, ü ä, ö, ü (trema alemão)
€ € (Euro)
â€" — (travessão)
’ ' (apóstrofo tipográfico)

Se você vê Ã seguido de outro caractere, UTF-8 foi lido como Latin-1.

Verificar os Bytes Brutos

Em Python:

with open('arquivo.csv', 'rb') as f:
    print(f.read(100))
Enter fullscreen mode Exit fullscreen mode

Se você vê \xc3\xa9 onde espera "é", o arquivo é UTF-8. Se vê \xe9, é Latin-1.

Verificar o Que a Página Declara

No DevTools do navegador:

document.characterSet  // Retorna a codificação real usada
Enter fullscreen mode Exit fullscreen mode

Corrigindo Arquivos Corrompidos

O Truque da Recodificação

Se UTF-8 foi lido como Latin-1 por engano, você pode reverter:

# Ler como Latin-1 (como foi interpretado erroneamente)
with open('corrompido.csv', 'r', encoding='latin-1') as f:
    text = f.read()

# Codificar de volta para bytes Latin-1, depois decodificar como UTF-8
fixed = text.encode('latin-1').decode('utf-8')

with open('corrigido.csv', 'w', encoding='utf-8') as f:
    f.write(fixed)
Enter fullscreen mode Exit fullscreen mode

Isso só funciona se a corrupção foi uma simples interpretação errada. Corrupção dupla ou encodings misturados são mais difíceis.

Forçar o Excel a Ler UTF-8

O Excel frequentemente ignora UTF-8. Duas alternativas:

Opção 1: Adicionar BOM

Um Byte Order Mark no início do arquivo sinaliza UTF-8:

with open('arquivo.csv', 'w', encoding='utf-8-sig') as f:
    f.write(data)
Enter fullscreen mode Exit fullscreen mode

Opção 2: Assistente de Importação

Em vez de dar duplo clique no CSV, use Dados → De Texto/CSV e especifique a codificação UTF-8 manualmente.

Google Planilhas como Intermediário

O Google Planilhas lida com encoding melhor que o Excel. Importe o CSV lá, depois exporte para XLSX. O arquivo Excel preservará os caracteres corretamente.

Prevenindo Problemas de Encoding

Se Você Está Exportando Manualmente

Use ferramentas que lidam com encoding corretamente. O HTML Table Exporter preserva Unicode ao longo de todo o processo de exportação, evitando os erros de conversão que causam mojibake.

Para exportações CSV, se sua ferramenta oferece opções de encoding, escolha UTF-8 com BOM para compatibilidade com Excel.

Se Você Está Construindo Ferramentas de Extração

Sempre seja explícito sobre a codificação:

# Escrevendo CSV
with open('saida.csv', 'w', encoding='utf-8', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(data)

# Lendo HTML
response = requests.get(url)
response.encoding = response.apparent_encoding  # Auto-detecção
html = response.text
Enter fullscreen mode Exit fullscreen mode

Para JavaScript/extensões de navegador:

// Blob com encoding explícito
const blob = new Blob(['\ufeff' + csvContent], { 
  type: 'text/csv;charset=utf-8;' 
});
Enter fullscreen mode Exit fullscreen mode

O \ufeff é o BOM que ajuda o Excel.

Se Você Está Usando Pandas 

# Leitura
df = pd.read_csv('arquivo.csv', encoding='utf-8')

# Escrita com BOM para Excel
df.to_csv('saida.csv', encoding='utf-8-sig', index=False)
Enter fullscreen mode Exit fullscreen mode

Caracteres Especiais Que Causam Problemas

Aspas Tipográficas e Apóstrofos

Processadores de texto convertem aspas retas em curvas:

  • ' → ' (U+2019)
  • " → " " (U+201C, U+201D)

Esses são multi-byte em UTF-8 e quebram em Latin-1.

Travessão e Meia-Risca

  • — (travessão, U+2014)
  • – (meia-risca, U+2013)

Comuns em dados financeiros e editoriais.

Espaços Não Quebráveis

Espaço normal é 0x20. Espaço não quebrável é 0xA0 (Latin-1) ou 0xC2 0xA0 (UTF-8).

São invisíveis mas quebram comparações de strings e parsing.

# Normalizar espaços
text = text.replace('\xa0', ' ')
Enter fullscreen mode Exit fullscreen mode

Símbolos de Moeda

€, £, ¥, R$ são todos fora do ASCII e codificam de forma diferente em UTF-8 vs Latin-1.

Referência Rápida

Problema Causa Provável Correção
à seguido de caractere UTF-8 lido como Latin-1 Recodificar ou especificar UTF-8 na importação
? ou □ substituindo caracteres Encoding não suporta o caractere Usar UTF-8 em todo o processo
Excel mostra lixo Excel adivinhou encoding errado Usar UTF-8 BOM ou assistente de importação
Caracteres invisíveis quebrando dados Espaços não quebráveis ou chars de largura zero Normalizar espaços em branco

A Regra Fundamental

Combine a codificação em cada etapa. Exporte como UTF-8. Abra como UTF-8. Salve como UTF-8.

No momento em que uma etapa usa uma codificação diferente, os caracteres corrompem.

Na dúvida, UTF-8 com BOM é a escolha mais segura para arquivos que vão passar pelo Excel. Para saber quais extensões Chrome lidam melhor com encoding na exportação de tabelas, confira nossa comparação das melhores extensões Chrome para exportar tabelas.

Quer exportações que lidam com encoding corretamente? Saiba mais em gauchogrid.com/pt-br/html-table-exporter ou experimente o HTML Table Exporter grátis na Chrome Web Store.

Top comments (0)