Escreva O Nome Dos Numeros

Como escrever números por extenso em português

Escrever números por extenso é uma daquelas coisas que todo mundo aprende na escola, mas na prática as pessoas travam com valores maiores ou combinações estranhas. Eu já vi desenvolvedores perderem tempo escrevendo conversores do zero porque não encontraram uma biblioteca quelidasse bem com milhões e bilhões em português do Brasil. A estrutura funciona em camadas. Cada grupo de três dígitos tem seu próprio sufixo: mil, milhão, bilhão, trilhão. O problema é que "mil" não varia no plural, então 2.000 é "dois mil" e não "dois miles". Já "milhão" varia: "dois milhões". As casas decimais também seguem regras próprias, com "vírgula" seguido do valor por extenso. Um detalhe que muita gente esquece: o "e" aparece apenas entre a centena e as dezenas/unidades dentro do mesmo bloco de três dígitos. Por exemplo, 1.199 é "mil cento e noventa e nove". Note que tem um "e" entre "cento" e "noventa", e outro entre "noventa" e "nove". Mas entre os blocos não se usa "e": 2.000.001 é "dois milhões e um", não "dois milhões e um".

Implementação prática

Se você precisa disso em código, existem bibliotecas maduras. No Python, a lib `num2words` com o parâmetro `lang='pt-BR'` resolve 99% dos casos. No JavaScript, o `number-to-words` ou `pt-br-number-to-words` fazem o serviço. O tricky é lidar com casas decimais e valores negativos, que muitas bibliotecas tratam de formas diferentes. Eu tive um problema específico onde o valor vinha como string de uma API financeira com vírgula decimal: "1.234,56". A biblioteca esperava um número float, então precisei um pré-processamentoconvertendo a string, substituindo o ponto de milhar e a vírgula decimal pelos formatos aceitos. O workaround foi limpar os pontos de milhar, trocar a vírgula por ponto e então passar para a função de conversão.

Pegadinhas comuns

Valores entre 10 e 15 têm formas irregulares: dez, onze, doze, treze, quatorze (ou catorze, dependendo da variante), quinze. Não existe padrão morfólogica aqui, então qualquer implementaçãodeve ter um dicionário fixo para esses casos. Outra pegada: 16 a 19 seguem o padrão "dez + unidade" com ligação, mas 20 a 99 usam a estrutura "dezena + e + unidade", exceto quando a unidade é zero. O valor 1.000.000.000 é "um bilhão" em português brasileiro, mas "mil milhões" em português europeu. Se seu sistema atende múltiplos mercados, isso pode ser uma fonte sutil de bug. O mesmo vale para "milhar" vs "miles".

Código de exemplo

from num2words import num2words

print(num2words(1234, lang='pt-BR'))
saída: mil duzentos e trinta e quatro

print(num2words(1234567, lang='pt-BR'))
saída: um milhão, duzentos e trinta e quatro mil, quinhentos e sessenta e sete

print(num2words(1234.56, lang='pt-BR'))
saída: mil duzentos e trinta e quatro reais e cinquenta e seis centavos

A biblioteca já lida com moeda se você passar o contexto correto, o que é útil para sistemas financeiros. Para valores muito grandes, acima de quatrilhões, o comportamento pode variar conforme a versão da biblioteca.

Limitações

Nenhuma solução é perfeita. Valores negativos, ordinais e fracionários nem sempre são bem tratados. A biblioteca `num2words` suporta ordinais com o parâmetro `ordinal=True`, mas a formatação de frações ainda deixa a desejar. Para uso em produção, teste sempre com edge cases do seu domínio específico antes de confiar cegamente na saída.

Alternativas

Se você precisa de controle total ou está em um ambiente restrito sem dependências externas, implementar manualmente não é tão difícil. O algoritmo básico: divida o número em grupos de três dígitos da direita para a esquerda, converta cada grupo usando as regras de 1-999, e concatene com os sufixos apropriados. O processamento leva menos de 1ms para qualquer valor dentro do range de um inteiro de 64 bits.