Windows-1251 e BOM no CSV: como corrigir o arquivo antes de importar

Um arquivo pode parecer totalmente normal e mesmo assim estar com a codificação errada

Um arquivo CSV exportado de um sistema de contabilidade ou de banco de dados mais antigo muitas vezes nem é UTF-8. O Windows-1251, para texto em cirílico, e o Windows-1252, para os caracteres acentuados da Europa Ocidental, ainda são saídas comuns de sistemas criados anos atrás. Um programa de planilhas costuma abrir um arquivo assim sem reclamar, porque aplica sozinho o próprio palpite de codificação. Então o arquivo parece normal até o momento em que é lido por algo menos tolerante, como um script, um fluxo de importação ou um carregador de banco de dados, que supõe UTF-8 e recebe uma parede de caracteres embaralhados no lugar do texto que estava ali.

Um marcador de três bytes no início do arquivo pode quebrar um parser rigoroso

A marca de ordem de bytes (BOM) do UTF-8 é um marcador invisível, de apenas três bytes, que fica logo no início do arquivo para sinalizar que o texto seguinte é Unicode. Ela ajuda um programa como o Excel, que procura por ela. Mas vira um problema no momento em que o destino é um importador de JSON rigoroso ou um script que não a espera. Esses bytes extras acabam grudados no primeiro caractere do cabeçalho da primeira coluna, e uma coluna que deveria ser lida como “id” deixa de bater com esse nome em todos os lugares onde o resto do código a procura. Detectar e remover esse marcador antes da conversão, em vez de deixá-lo no arquivo resultante, evita uma divergência que pode ser difícil de rastrear depois.

A codificação certa, de forma automática, sem um menu de opções

Uma detecção de codificação confiável, como a que o CSV para JSON faz antes de ler uma única linha, procura primeiro uma marca de ordem de bytes, depois tenta validar o resto dos bytes estritamente como UTF-8 e só recorre ao Windows-1251 ou ao Windows-1252, conforme a distribuição dos bytes de valor mais alto, se essa validação estrita falhar. Essa ordem importa. Um arquivo que já é UTF-8 nunca é posto em dúvida a ponto de ser lido como outra coisa, enquanto um arquivo que não é UTF-8 é identificado corretamente, em vez de ser empurrado como UTF-8 e virar caracteres embaralhados no caminho. A mesma detecção fica na frente do CSV para Excel, para os casos em que o destino é uma planilha, e não um script.

Os tipos de dados importam tanto quanto a codificação dos caracteres

Acertar a codificação dos caracteres resolve só metade do que quebra em uma conversão de CSV para JSON. A outra metade é decidir quais valores devem virar números ou booleanos no JSON e quais devem continuar como texto simples. Um valor como 00123 que vira o número 123 perde o zero à esquerda para sempre no instante em que essa conversão acontece, e um identificador com mais de uns quinze dígitos é arredondado no momento em que vira um número de ponto flutuante comum, em vez de continuar como texto. Os dois devem ficar como strings, porque convertê-los muda os próprios dados, e não só a formatação ou a aparência.

Um cabeçalho duplicado pode quebrar a importação de um jeito diferente da codificação errada

Objetos JSON não podem ter duas propriedades com a mesma chave. Por isso, um arquivo de origem com duas colunas que calham de ter o mesmo nome no cabeçalho, o que não é raro em exportações montadas a partir de mais de um sistema, precisa que essas duplicatas ganhem nomes distintos durante a conversão. Senão, os dados da segunda coluna sobrescrevem os da primeira em todos os objetos gerados, sem nenhum aviso. É uma falha diferente da codificação ou dos tipos, mas igualmente capaz de corromper uma importação sem que ninguém perceba. Vale conferir se a ferramenta de conversão avisa quando isso acontece, em vez de resolver a colisão às escondidas, e passar o resultado pela ferramenta Formatar JSON mostra as chaves renomeadas em um relance.

Passo a passo: conferir o arquivo antes da importação

Converta o arquivo exportado uma vez no CSV para JSON, com o delimitador e a codificação no automático, e depois confira os dois palpites: mande o resultado para a ferramenta Formatar JSON, um dos próximos passos que a página oferece, e leia os primeiros registros. Cirílico embaralhado ou acentos quebrados indicam que o palpite da codificação errou; uma única chave comprida, com os separadores ainda dentro dela, indica que quem errou foi o palpite do delimitador. Ajuste à mão o que estiver errado e converta de novo: o menu de codificação oferece Windows-1251, Windows-1252, UTF-8 com ou sem BOM e UTF-16 LE; o de delimitador, vírgula, ponto e vírgula, tabulação, barra vertical ou um caractere à sua escolha. Um arquivo cujo separador ou codificação não dá para entender de jeito nenhum é recusado com uma mensagem, em vez de ser convertido em algo sem sentido.

Em seguida, decida como os valores são tipados: o padrão já deixa como texto os valores com zero à esquerda e os identificadores longos, e, para um arquivo feito de códigos, números de telefone ou números de conta, colocar Tipos de valor em Manter tudo como texto não converte nada. Com o resultado aberto no Formatar JSON, procure dois sinais de uma origem bagunçada: duas colunas com o cabeçalho id saem como id e id_2, e uma linha com mais campos que o cabeçalho leva os campos a mais sob uma chave __extra. Os dois são mais baratos de corrigir no arquivo de origem do que no sistema que engasgaria com eles depois. Até vinte arquivos, 300 MB no total, passam em um único lote sem sair da aba do navegador.