Como escrever números por extenso sem perder a sanidade
Na prática, converter números para extenso parece trivial até você se deparar com um valor como 1.010.090,23 e perceber que a régua mental que aprendeu na escola não cobre tudo que precisa. O sistema é lógico, sim, mas ele tem armadilhas que ninguém te avisa antes.
nome dos numeros por extenso — regra prática
O segredo é saber dividir o número em grupos de três algarismos, da direita para a esquerda, e aplicar a tabela de centenas, dezenas e unidades dentro de cada grupo. Você não decora tudo de uma vez. Você aprende os blocos e vai compondo. O número 347.821, por exemplo, se lê como "trezentos e quarenta e sete mil e oitocentos e vinte e um". Note o "e" aparecendo em lugares específicos e sumindo em outros. Esse é o primeiro filtro de quem ainda está começando. Existem duas regras básicas que todo mundo precisa ter na ponta da língua:
- De 100 a 999, usa-se "e" entre a centena e o resto, e entre dezenas e unidades quando a dezena não é redonda. "Trezentos e cinquenta e dois". - Milhares e milhões seguem a lógica dos grupos de três. "Um milhão", "dois milhões", "trezentos e quarenta e cinco milhões". A palavra "mil" funciona como separador de grupo, não como conectivo.
O que pega muita gente é o tratamento do zero. Se um grupo inteiro é zero, você simplesmente não o pronuncia. 1.000.002 não tem "mil" no meio. É "um milhão e dois". Mas 1.002.000 tem o "mil" e zero no último grupo fica subentendido. Isso gera confusão porque o cérebro quer preencher cada grupo com algo falado, mas a norma não exige isso.
👉 Clique no botão abaixo para saber mais sobre o assunto!
o problema que ninguém conta
Eu já perdi meia hora num contrato porque o valor era 1.200.000,00 e a planilha gerava "um milhão e duzentos mil reais". O problema real era que o setor jurídico queria a forma completa com os centavos também, então precisávamos de "um milhão e duzentos mil reais e zero centavos". Ninguém escreve isso na regra, mas na prática exigem. A solução foi montar uma função que, além de convertir a parte inteira, formatasse a parte fracionária como "e zero centavos" ou "e cinquenta centavos" dependendo do valor, e juntasse tudo com a palavra "reais" antes da vírgula dos centavos. Simples, mas só funciona se você tratar os dois grupos separadamente. Outro detalhe técnico que passa despercebido: a forma "cem" vs "cento". Quando o número é exatamente 100, usa-se "cem". Em qualquer outro caso dentro da casa das centenas, usa-se "cento". Então 100 é "cem", mas 150 é "cento e cinquenta", e 1.100 é "mil e cem". Essa mudança de "cento" para "cem" só no exato valor de 100 dentro de cada grupo é algo que as implementações automáticas erram com frequência. Eu descobri isso na marra, num sistema de emissão de notas onde a versão 1.0 gerava "mil e cento" para 1.100, o que está errado.
como fazer funcionar de verdade
A abordagem mais limpa é dividir o número em três partes: inteiro, décimos e centésimos. Para a parte inteira, você itera sobre os grupos de três dígitos, da direita para a esquerda, aplicando os sufixos "mil", "milhões", "bilhões", e assim por diante. Para cada grupo de três, você converte as centenas, depois as dezenas, depois as unidades, inserindo "e" nos lugares corretos. Um insight importante: a conjunção "e" só aparece entre centena e dezenas/unidades, e entre dezenas e unidades. Nunca entre grupos. Você não diz "trezentos e quarenta e sete mil e oitocentos". Diz "trezentos e quarenta e sete mil e oitocentos e vinte e um". O "e" que vem depois de "mil" é obrigatório apenas quando o grupo seguinte começa com 1 a 99, não com 100 a 999. Ou seja, 1.050 é "mil e cinquenta", mas 1.150 é "mil cento e cinquenta". Esse é um ponto que quase toda biblioteca genérica trata errado.
Para implementar, sugiro começar com uma tabela fixa para os números de 0 a 99, incluindo as formas especiais como "onze", "doze", "treze", "quatorze", "quinze", "vinte e um" até "vinte e nove", e os "vinte", "trinta", "quarenta", "cinquenta", "sessenta", "setenta", "oitenta", "noventa". A partir daí, a lógica de construção dos grupos maiores se resolve com concatenação condicional. Se você está programando isso, evite tentar fazer tudo numa única expressão. Separe a conversão de cada grupo de três dígitos numa função pura, e depois itere sobre os grupos aplicando os multiplicadores. Isso reduz bugs em cerca de 70% comparado a uma implementação monolítica, na minha experiência.
limitações e quando não usar
Esse método funciona bem para números até bilhões. Acima disso, a coisa complica porque a nomenclatura varia entre países. No Brasil, usa-se "bilhão" (10^9), mas em alguns contextos europeus e em sistemas antigos, "bilhão" pode significar 10^12. Se você precisa atender público internacional, trate isso como uma variável de configuração desde o início, senão volta a corrigir depois. Também vale dizer que números com muitas casas decimais, como valores contábeis com seis casas, geralmente não se escrevem por extenso da forma convencional. Nesse caso, o mais sensato é manter o formato numérico e usar a escrita por extenso apenas para a parte inteira, com uma nota lateral indicando o valor em centavos. Tentar converter 0,000347 para extenso é um exercício de masoquismo, não de boa prática.
Se o objetivo é automação pura, bibliotecas como a num2words para Python cobrem a maioria dos casos para português brasileiro, mas elas têm os mesmos problemas que mencionei com o "cento" vs "cem" e com a conjunção "e" entre grupos. Teste sempre com os valores de borda antes de confiar no resultado em produção. A versão manual, feita grupo por grupo, leva uns dez minutos para números de até seis dígitos. Com uma função bem feita, o tempo cai para menos de um milissegundo. O ganho real não é velocidade, é consistência. Ninguém errou um "mil e cento" num contrato depois que implementamos a correção daquela forma.
