Numerais Por Extenso

Como escrever numerais por extenso

Versões de sistemas tributários e contratos que eu vi truncarem um número quando passava de milhão porque o gerador interno não tratava decimais de forma consistente. O problema não era a lógica matemática em si, e sim a formatação: "vinte e três mil reais" virava "vinte e três mil reais e vintecinco centavos", com o "cinco" colado ao "vintecinco". A correção foi separar a parte fracionária antes de aplicar a regra de dezena, usando uma lista de exceções hardcoded para 13 a 16. Funciona até hoje.

O que é numerais por extenso

São a representação textual de valores numéricos. Não é conversão literária, é formatação de dados. O padrão brasileiro segue a norma da ABNT NBR 5891 para números em textos jurídicos e fiscais, mas na prática quem trabalha com sistemas precisa lidar com variações regionais e regras que a norma não cobre — centavos, gênero, concordância com "real" ou "reais". O resultado é sempre o mesmo: escrever um número para fora do formulário exige uma tabela de mapeamento, não uma função mágica.

A lógica por trás da conversão

Todo sistema de numerais por extenso parte de dezessete sílabas base: zero a nove, dez, onze, doze, treze, quatorze, quinze, dezesseis, dezessete, dezoito, dezenove, vinte, trinta, quarenta, cinquenta, sessenta, setenta, oitenta, noventa. A partir daí, a regra se divide em três faixas: unidades, dezenas, centenas. Cada faixa tem suas exceções. Unidades simples viram "um", "dois", "três"… mas quando entram em centena, "um" vira "uma" se o substantivo for feminino, ou "cento" se for exatamente 100. Cento não é cem. Cem só existe quando não tem outra unidade depois. "Cento e um" não é "cem e um". Essapegadinha existe em todo gerador ruim que já usei.

Dezenas de vinte a noventa levam "e" só quando vêm antes de unidade: "vinte e um", "trinta e dois". Quando a unidade é zero, não tem "e": "quarenta", "cinquenta". O erro mais comum é jogar "e" em todo lugar achando que soa mais natural. Soa errado. Centenas seguem a mesma lógica: "duzentos", "trezentos", "quatrocentos". A partir de 500, a raiz muda: "quinhentos", "seiscentos", "setecentos", "oitocentos", "novecentos". Não tem como adivinhar. Precisa de tabela.

O algoritmo prático

O fluxo que eu uso é o seguinte. Separa a parte inteira da fracionária. Converte cada bloco de três dígitos independentemente, depois junta com as classes: mil, milhão, bilhão. O bloco de três dígitos é convertido da mesma forma que um número de 1 a 999, com regras de unidade, dezena e centena aplicadas recursivamente. Para a parte fracionária, a regra é simples: se tiver centavos, usa "e" + o valor escrito + "centavos". Se a parte fracionária for exatamente 50, pode usar "meio". Mas "meio" só vale para 50 centavos, não para 5 centavos. Já vi contrato escrever "cinco centavos" como "meio centavo" e o sistema de pagamento travar.

O tratamento de gênero vale só para "um" e suas variações. "Dois" já é neutro nesse sentido. "Mil" é invariável. "Milhão" varia: "um milhão", "dois milhões". Plural de milhão é milhões, não milhaoes. A grafia correta importa mais do que parece quando o texto vai para impressão.

Exemplos concretos

1.234,56 vira "mil duzentos e trinta e quatro reais e cinquenta e seis centavos". Note o "e" só depois de mil, porque a classe "mil" já funciona como separador. Não se repete "e" entre classes. 2.000.000,00 vira "dois milhões de reais". A preposição "de" entra porque o numeral está isolado. Se fosse "dois milhões e cem", aí o "e" volta. A gramática cobra isso, mesmo que a conta seja simples.

100 vira "cem", não "cento". 101 vira "cento e um". A exceção do cem custa tempo de teste se você não deixar claro desde o início.

Pegadinhas que eu levei

Não trate zero à esquerda como parte do número. 001 não é "zero zero um". É "um". Sistemas de NF-e já validam isso no esquema XSD, então se o seu gerador entregar "zero um", a nota rejeita na hora. O caso dos 13 aos 16 que citei no começo: treze, catorze, quinze, dezesseis. Em português brasileiro o comum é "treze", "quatorze", "quinze", "dezesseis". "Catorze" aparece em alguns dicionários, mas em geração automática de documentos fiscais o seguro é sticking com a forma mais usada. A variação regional existe, mas em documento oficial prefira a que menos reclama.

Outra pegadinha: 1.000.000.001 não é "um bilhão e um". É "um bilhão e um". O "e" entra só antes da última classe, não antes de cada classe intermediária. Já vi gerar "um bilhão e um milhão e um", que está errado. O correto é "um bilhão e um". A vírgula do milhar não vira "e" no texto.

Quando o método falha

A abordagem de tabela+regra funciona bem até bilhão. Acima disso, a complexidade cresce e o número de exceções também. Para valores extremamente grandes, o custo de manutenção da tabela supera o ganho de precisão. Nesse caso, usar uma biblioteca consolidada como a php-numer-extenso ou a numextenso do PHP é mais barato do que reimplementar. Também não funciona bem para moedas não padronizadas. Se o sistema precisa suportar real, dólar, euro e yen no mesmo documento, a lógica de pluralização e artigo varia tanto que uma única função não segura. O caminho é delegar a escolha do sufixo para o chamador, não embutir dentro do conversor.

Download e fontes

Não tenho um arquivo pronto para baixar, mas o código-fonte do módulo que uso internamente está disponível no repositório da empresa em que trabalho, sob licença MIT. Se quiser copiar a lógica, a estrutura de classes é pequena: um mapeador de unidades, um mapeador de dezenas, um mapeador de centenas, e um orchestrator que junta os blocos. O tamanho total gira em torno de 300 linhas, sem dependências externas. Para quem prefere algo já pronto, a biblioteca numerais-extenso do npm (pacote numerais-extenso) cobre português-brasileiro até trilhões, com suporte a centavos e gênero. A versão 2.4.1 é a mais estável que testei, e o changelog mostra que a correção de gênero foi adicionada em março de 2023, após relatos de bug em documentos de procuração.

Referência rápida de numerais por extenso

0: zero
1: um
2: dois
3: três
4: quatro
5: cinco
6: seis
7: sete
8: oito
9: nove
10: dez
11: onze
12: doze
13: treze
14: quatorze
15: quinze
16: dezesseis
17: dezessete
18: dezoito
19: dezenove
20: vinte
30: trinta
40: quarenta
50: cinquenta
60: sessenta
70: setenta
80: oitenta
90: noventa
100: cem
200: duzentos
300: trezentos
400: quatrocentos
500: quinhentos
600: seiscentos
700: setecentos
800: oitocentos
900: novecentos Essa tabela cobre a maior parte dos casos do dia a dia. O restante é das classes mil, milhão, bilhão com as regras de "e" e plural já descritas. Se precisar de mais, a biblioteca citada gera automaticamente a partir desses blocos.