Como Corrigir Mojibake e Erros de Codificação Unicode: Detecção, Reparo e Prevenção

Mojibake (文字化け) é um termo japonês que significa "transformação de caracteres": descreve o texto embaralhado que aparece quando uma string é interpretada com a codificação de caracteres errada. Em vez de "résumé" você vê "résumé". Em vez de um apóstrofo tipográfico você vê "’". Os caracteres não estão corrompidos no nível de bytes — os bytes estão intactos. O problema é que o software que os lê usa o manual errado para traduzir bytes em caracteres.

O problema da tradução byte-caractere

Toda codificação de caracteres é um mapeamento entre números (bytes) e caracteres. A letra "e" é o byte 0x65 em praticamente todas as codificações. Mas um "é" acentuado é representado de forma diferente dependendo da codificação: em UTF-8 é a sequência de dois bytes 0xC3 0xA9, enquanto em Latin-1 é o byte único 0xE9. Quando um programa lê os bytes UTF-8 0xC3 0xA9 usando regras Latin-1, ele produz dois caracteres separados — Ã e © — em vez do único caractere é. Essa substituição é o mojibake.

• é vira é — bytes UTF-8 lidos como Latin-1 (o padrão mais comum)
• ü vira ü — a mesma discrepância para o u com trema alemão
• ’ (apóstrofo direito) vira ’ — aspas tipográficas UTF-8 mal lidas como Latin-1
• – (travessão curto) vira – — comum em texto colado do Word ou PDF
• Caractere de substituição Unicode — um caractere válido foi forçado em um contexto que não consegue representá-lo

Erros de codificação são um problema de fronteiras do sistema. Ocorrem quando o texto cruza uma fronteira — entre um arquivo e um aplicativo, entre um banco de dados e uma API, entre um servidor web e um navegador — e o lado emissor e o receptor discordam sobre qual codificação o texto usa. Em um mundo onde UTF-8 é o padrão universal, esses erros deveriam ser raros. Mas são comuns porque sistemas legados, ferramentas do Windows e certos bancos de dados ainda usam codificações antigas por padrão.

As fontes mais comuns

• Arquivos CSV do Excel — o Excel salva CSV como Windows-1252 no Windows por padrão, não UTF-8. Ao abrir no Linux ou no Python, os caracteres acentuados se corrompem.
• Bancos MySQL com charset latin1 — instalações antigas do MySQL usam `latin1` por padrão para os conjuntos de caracteres das colunas. Armazenar dados UTF-8 neles causa mojibake na leitura.
• Cabeçalhos e corpos de e-mail — clientes de e-mail que não declaram um charset, ou que interpretam mal uma declaração de charset, produzem mojibake nos campos De, Assunto e corpo.
• Extração de texto de PDF — arquivos PDF incorporam fontes com mapeamentos de glifos personalizados que nem sempre correspondem aos pontos de código Unicode padrão, produzindo saída embaralhada ao copiar.
• Respostas HTTP sem charset no Content-Type — um servidor que envia `Content-Type: text/html` sem `; charset=utf-8` deixa o navegador adivinhar, e ele frequentemente adivinha errado.

UTF-8 vs Windows-1252 — a discrepância mais frequente

Windows-1252 (também chamado CP1252) é um superconjunto do Latin-1 desenvolvido pela Microsoft para as línguas da Europa Ocidental. Usa um byte por caractere e cobre 256 pontos de código — suficiente para inglês, francês, alemão, espanhol e português. UTF-8 usa um a quatro bytes por caractere e cobre todos os 1,1 milhão de pontos de código Unicode. Quando texto UTF-8 é lido como Windows-1252, as sequências multibyte produzem os característicos padrões de mojibake de dois ou três caracteres. O inverso — texto Windows-1252 lido como UTF-8 — produz caracteres de substituição (□ ou ?) porque os bytes altos isolados não são sequências UTF-8 válidas.

Texto sem metadados de codificação não é texto — é uma sequência de bytes esperando para ser mal interpretada.

Detectar um problema de codificação geralmente é simples: a aparência visual do mojibake é distintiva o suficiente para identificar o padrão da discrepância. Mas para detecção programática, ou para texto que parece correto mas contém problemas invisíveis, você precisa de técnicas específicas.

Reconhecimento visual de padrões

O diagnóstico mais confiável é o próprio padrão de mojibake. Texto UTF-8 lido como Latin-1 produz um prefixo característico "Ã" seguido de um segundo caractere — por exemplo, é para é, à para à, ü para ü. Pontuação tipográfica do Word ou de editores de texto rico produz sequências começando com †— por exemplo, ’ para ’ e “ para “. Se você vir essas sequências, a solução é recodificar os bytes de Latin-1 de volta para UTF-8.

Detecção programática de codificação

Para arquivos e fluxos de dados em que não é possível ver o conteúdo visualmente, use a biblioteca `chardet` (Python) ou o pacote `jschardet` (Node.js) para autodetectar a codificação a partir dos padrões de bytes. Essas bibliotecas analisam a frequência e a distribuição dos valores de byte para identificar a codificação mais provável. Não são 100% precisas — strings curtas e strings com poucos caracteres não ASCII são mais difíceis de classificar com confiança — mas lidam bem com os casos comuns. Use o Consultor de Caracteres Unicode para inspecionar pontos de código individuais e suas representações de bytes esperadas ao depurar caracteres específicos.

A maneira mais rápida de corrigir texto com mojibake é a Ferramenta de Reparo Unicode e de Codificação. Ela roda inteiramente no seu navegador — sem upload para servidor, sem registro — e trata automaticamente as discrepâncias UTF-8/Latin-1 mais comuns, a corrupção de aspas tipográficas e a remoção de caracteres invisíveis.

Diferentes discrepâncias de codificação produzem padrões visuais diferentes. Reconhecer o padrão indica tanto a causa quanto a correção certa — qual par de codificações aplicar ou qual operação de reparo executar.

O problema da dupla codificação

Uma variante particularmente danosa é o duplo mojibake — quando o texto foi mal codificado duas vezes. Produz sequências como © em vez de ©, ou Æ¢ em vez de ¢. Acontece quando texto já com mojibake é salvo e depois lido com a codificação errada uma segunda vez. O processo de reparo exige duas rodadas de recodificação em ordem inversa. A Ferramenta de Reparo Unicode e de Codificação detecta e trata automaticamente os padrões de dupla codificação mais comuns.

A correção de longo prazo para o mojibake é impor UTF-8 em cada fronteira do seu sistema — armazenamento de arquivos, banco de dados, API e camada web. Estes são os lugares específicos onde as declarações de codificação devem ser explícitas.

Bancos de dados — declare UTF-8 em toda parte

No MySQL e MariaDB, defina o conjunto de caracteres padrão como `utf8mb4` (não `utf8` — o `utf8` do MySQL cobre apenas sequências de 3 bytes e exclui emojis e caracteres Unicode raros). Defina em três níveis: o padrão do servidor no `my.cnf`, o charset do banco de dados e os charsets das colunas individuais. No PostgreSQL, o padrão já é UTF-8 em instalações novas. No SQLite, o texto é sempre UTF-8 por padrão.

-- MySQL: set all levels to utf8mb4
ALTER DATABASE mydb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Arquivos — salve sempre como UTF-8

Ao salvar arquivos de texto, exportações CSV ou arquivos de configuração, escolha sempre UTF-8 como codificação. No VS Code, a codificação aparece na barra de status — clique para alterar. No Excel, exporte CSV usando "CSV UTF-8 (separado por vírgulas)" em vez do padrão "CSV (separado por vírgulas)". Para scripts Python que gravam arquivos, sempre passe `encoding='utf-8'` explicitamente na chamada `open()` em vez de confiar no padrão do sistema. Limpe o texto após colar de fontes externas com o Limpador de Texto de E-mail, que remove caracteres invisíveis e normaliza espaços automaticamente.

APIs e HTTP — declare o charset no Content-Type

Toda resposta HTTP que contenha texto deve incluir uma declaração de charset: `Content-Type: application/json; charset=utf-8` ou `Content-Type: text/html; charset=utf-8`. Sem ela, o cliente adivinha — e clientes HTTP antigos usam Latin-1 por padrão para respostas `text/html`. Para páginas HTML, adicione também `<meta charset="UTF-8">` como primeiro elemento dentro de `<head>`. Para APIs JSON, `Content-Type: application/json` implica UTF-8 segundo a RFC, mas ser explícito elimina a ambiguidade e previne problemas com clientes não conformes.

Checklist de codificação por contexto

• Arquivos Python: adicione o cabeçalho `# -*- coding: utf-8 -*-` para Python 2; no Python 3 é desnecessário, mas inofensivo
• Strings de conexão MySQL: inclua `charset=utf8mb4` no DSN — ex.: `mysql+pymysql://user:pass@host/db?charset=utf8mb4`
• Leituras de arquivo no Node.js: passe `encoding: "utf8"` ao `fs.readFile()` ou use `Buffer.from(data).toString("utf8")`
• Documentos XML e HTML: sempre inclua `<?xml version="1.0" encoding="UTF-8"?>` e `<meta charset="UTF-8">`
• Bibliotecas de envio de e-mail: defina `Content-Type: text/plain; charset=utf-8` e `Content-Transfer-Encoding: 8bit` ou `quoted-printable`

Além da clássica discrepância UTF-8/Latin-1, outros dois problemas de Unicode produzem bugs sutis mais difíceis de detectar: discrepâncias de normalização e caracteres invisíveis. Ambos podem fazer comparações de strings falharem, buscas em banco de dados não encontrarem registros e resultados de busca ficarem incompletos — mesmo quando o texto parece idêntico na tela.

Formas de normalização Unicode

O Unicode permite representar o mesmo caractere visível de várias maneiras. A letra "é" pode ser codificada como um único ponto de código précomposto (U+00E9) ou como a combinação de "e" (U+0065) seguida de um acento agudo combinante (U+0301). Ambas parecem idênticas na tela, mas são sequências de bytes diferentes que falham em comparações de igualdade de strings. É por isso que buscar "résumé" em um banco de dados às vezes não encontra resultados — o texto armazenado usa outra forma de normalização. NFC (Decomposição Canônica seguida de Composição Canônica) é a forma normal recomendada para a maioria dos aplicativos. A Ferramenta de Reparo Unicode e de Codificação normaliza o texto para NFC como parte do processo de reparo.

Caracteres invisíveis e de largura zero

Caracteres de largura zero são pontos de código Unicode que ocupam espaço em uma string mas não renderizam nada visível. Frequentemente inseridos por processadores de texto, aplicativos de chat e operações de copiar e colar de PDFs ou páginas web. Os culpados comuns são o espaço de largura zero (U+200B), o espaço sem quebra de largura zero (U+FEFF, também a marca de ordem de bytes) e vários caracteres de controle bidirecionais de texto (U+200E, U+200F, U+202A-U+202E). Esses caracteres quebram padrões regex, confundem tokenizadores e fazem strings de aparência idêntica serem comparadas como desiguais. Use o Consultor de Caracteres Unicode para identificar pontos de código suspeitos em uma string.