Como transformar números em extenso na prática
A maioria das pessoas que precisa escrever valores por extenso enfrenta o mesmo problema: planilhas cheias de valores em reais que precisam virar texto para contratos, cheques ou documentos judiciais. Fazer isso manualmente é lento e generador de erro. O processo básico é simples — dividir o número em grupos de milhares e aplicar regras de concordância —, mas existem detalhes que quem nunca fez isso pelo menos meia dúzia de vezes acaba ignorando. O cerne da questão é entender a estrutura do sistema numérico brasileiro. Cada grupo de três dígitos recebe um suffixo: mil, milhão, bilhão. A palavra "mil" é invariável, o que significa que nunca se acrescenta "s" depois dela, independentemente do valor. Já "milhão" varia no plural. Isso parece trivial até você se deparar com um número como 1.500, que vira "um mil e quinhentos", não "umilies e quinhentos". Erros assim aparecem todo dia em documentos revisados tardiamente.
Escrevendo por extenso os números com precisão
Para converter um número em extenso de forma confiável, o fluxo mais prático envolve três etapas. Primeiro, você quebra o número em períodos de três dígitos a partir da direita. Segundo, converte cada período isoladamente usando as regras de centena, dezena e unidade. Terceiro, concatena tudo com os conectivos adequados ("e" para ligar centena a dezena/unidade dentro do mesmo período, e "e" também entre períodos quando necessário). Dentro de cada período de três dígitos, a regra é: se a casa das centenas for diferente de zero, escreve-se "cem", "duzentos", "trezentos" etc. Se for zero e houver dezenas ou unidades, usa-se a conjunção "e" entre a centena (se existir) e o resto. Por exemplo, 473 é "quatrocentos e setenta e três". Já 500 é apenas "quinhentos", sem "e". Isso gera confusão porque as pessoas tendem a colocar "e" em todo lugar por padrão, achando que é mais seguro. Não é. O "e" só entra quando a casa imediatamente seguinte à centena é não-nula e a centena em si também existe.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Um detalhe que muita gente desconhece: a palavra "mil" deve sempre aparecer antes dos restantes dígitos do período seguinte, mesmo quando esse período começa com zero. Ou seja, 1.002.003 é "um milhão, dois mil e três", não "um milhão, zero mil e três". O "zero" nunca se pronuncia em extenso em valores monetários. Isso é consenso normativo para cheques e documentos financeiros no Brasil. O maior problema que eu enfrentei na prática aconteceu há alguns anos, trabalhando com a geração automática de títulos de crédito. Havia um caso limite com o número 112.000.001, que deveria ser "cento e doze milhões e um real". Mas o sistema que estávamos usando converteu para " cento e doze milhões e um reais", com "reais" no plural errado, porque a lógica interna aplicava pluralização baseada apenas no último dígito, ignorando o contexto do período inteiro. A correção foi implementar uma regra específica: quando o período final é "001", o substantivo (real, dólar, euro) permanece no singular, independente de qualquer outro fator. Isso economizou horas de retrabalho em lotes de milhares de notas promissórias.
Se você precisa de uma solução pronta, a biblioteca mais usada no ecossistema Python é a num2words. Ela roda localmente, não depende de internet, e suporta português do Brasil nativamente. A instalação é feita com pip install num2words, e o uso é direto: num2words(1234567, lang='pt_BR'). O retorno é uma string com o número por extenso, e o tempo de conversão de um lote de 10.000 números costuma ficar entre 8 e 12 segundos em hardware comum. Existem limitações importantes. A biblioteca não lida bem com formatos monetários embutidos — ela converte o número puro, sem a palavra "real" ou "reais". Você precisa concatenar manualmente. Além disso, para valores acima de 999 trilhões, a saída pode ficar estranha, porque o suporte a trilhão e superiores no português brasileiro ainda é inconsistente entre as versões. Se você trabalha com valores dessa magnitude, prefira construir uma wrapper própria ou usar uma biblioteca como a br_number, que dá mais controle sobre a formatação final.
Outro ponto cego: decisões entre "e" e vírgula. Em documentos formais, alguns setores ainda exigem vírgula separando períodos (ex: "mil, duzentos e trinta"), enquanto outros aceitam apenas a conjunção "e". A num2words adota o padrão mais comum, mas se o seu cliente ou departamento jurídico tiver uma norma interna específica, vale a pena testar com amostras reais antes de automatizar em produção.
