Repository files navigation

O projeto Extenso.js foi criado com o objetivo de fornecer uma solução simples e eficiente para a conversão de números para texto em português.

A motivação por trás deste projeto é atender a uma necessidade comum em diversas aplicações financeiras, educativas e administrativas, onde é frequentemente necessário converter valores numéricos em palavras para fins de documentação, cheques, faturas e outros documentos formais.

Nossa ambição com o Extenso.js é tornar esta biblioteca uma referência para desenvolvedores que precisam dessa funcionalidade em suas aplicações, promovendo a padronização e simplificação do processo de conversão de números para texto.

• Suporte a números de até duodecilhões (10³⁹ ou 10⁷²).
• Suporte a números negativos e decimais.
• Suporte a múltiplas moedas (BRL, EUR, USD e mais).
• Suporte a diferentes dialetos do português (Brasil e Portugal).
• Suporte a BigInt para números extremamente grandes.
• Suporte à escala curta e longa de números.
• Suporte à personalização de gênero gramatical.
• Suporte à formatação flexível (vírgula ou ponto como separador decimal).
• Zero dependências.

NOTA: Observe que 10³⁹ é o limite para a escala curta enquanto que 10⁷² é o limite para a escala longa.

npm install extenso

Ou se preferir, com Yarn:

yarn add extenso

importextensofrom'extenso'

extenso(number[,options])

O valor que deverá ser escrito por extenso (obrigatório).

Se o valor for do tiponumber, recomenda-se que ele seja um número com parte inteira segura, ou seja, o valor deve ser válido na verificação comNumber.isSafeInteger(), caso contrário, é recomendado que os números sejam encapsulados emstring devido ao fato de que, no JavaScript, números (do tiponumber) maiores que 9 quatrilhões perdem precisão. Alternativamente, pode-se utilizar númerosBigInt (do tipobigint) adicionandon no final, por exemplo,10000000000000001n (leia este artigo para mais informações), porém você estará limitado a números inteiros apenas, não podendo representar números decimais.

Números envolvidos emstrings deverão seguir o formato natural de escrita de números. Você pode usar- no início para representar números negativos e vírgula (,) ou ponto (.) para separação de milhares e decimais, seguindo, por padrão, o formato de escrita do Brasil (ou seja, com vírgula como separador decimal). Esse formato pode ser alterado conforme a preferência, utilizando o parâmetrodecimalSeparator como será visto mais adiante.

Opções de escrita (opcional).

• mode [string]
• scale [string]
• locale [string]
• currency.code [string]
• number.gender [string]
• decimalSeparator [string]

Define o modo de escrita do número.

Opções disponíveis:

• number [default] - Escrever somente o número por extenso.
• currency - Escrever o número como valor monetário.
• digit - Escrever o número por extenso em dígitos.

Exemplos:

extenso('123')//=> 'cento e vinte e três'extenso('123',{mode:'number'})//=> 'cento e vinte e três'extenso('123',{mode:'currency'})//=> 'cento e vinte e três reais'extenso('123',{mode:'digit'})//=> 'um dois três'

Define a escala de escrita (curta ou longa).

As escalas curta e longa são dois sistemas de escrita dos números. A escala curta é a utilizada no Brasil, enquanto a escala longa é utilizada no restante dos países de língua portuguesa.

A escrita diverge somente em números iguais ou superiores a um milhar de milhões (≥10⁹), números inferiores a isso seguem com a escrita idêntica em ambas as escalas.

Mais informaçõesaqui [Wikipédia].

• short [default] - Para escrever o número utilizando a escala curta.
• long - Para escrever o número utilizando a escala longa.

Exemplos:

extenso('2.000.000.001')//=> 'dois bilhões e um'extenso('2.000.000.001',{scale:'short'})//=> 'dois bilhões e um'extenso('2.000.000.001',{scale:'long'})//=> 'dois mil milhões e um'

Define o separador de inteiro e decimal.

No português, o separador de inteiro e decimal mais comum é a vírgula (comma). No entanto, em outros países, pode ser necessário usar o ponto (point) como separador decimal. Nesse caso você pode utilizar o parâmetrodecimalSeparator para definir outro separador de decimal (point), no entanto, isso só é necessário se o número fornecido esteja encapsulado emstring.

Observe que caso o separador decimal sejapoint (.) então o separador de milhar automaticamente serácomma (,) e vice-versa.

• comma [default] - Para usarvírgula como separador (ex.3,14).
• point - Para usarponto como separador (ex.:3.14)

Exemplos:

extenso('3,14')//=> 'três inteiros e quatorze centésimos'extenso('3,14',{decimalSeparator:'comma'})//=> 'três inteiros e quatorze centésimos'extenso('3.14',{decimalSeparator:'point'})//=> 'três inteiros e quatorze centésimos'

Define a localização (dialeto) para a escrita.

A escrita de alguns números pode variar de país para país (e talvez até de região para região); por exemplo, o número 16 é escritodezesseis no Brasil, enquanto em Portugal é escritodezasseis. A configuração dessas diferenças é feita aqui.

Até o momento, são suportados os dialetosbr ept de acordo as diferenças conhecidas entre o português do Brasil e o português de Portugal. Caso você necessite de um dialeto diferente, abra umaissue e vamos discutir como adaptar essas caracteristicas ao projeto para deixá-lo o mais completo possível.

• br [default] - Para escrever no dialeto do Brasil.
• pt - Para escrever no dialeto de Portugal.

Exemplos:

extenso('16')//=> 'dezesseis'extenso('16',{locale:'br'})//=> 'dezesseis'extenso('16',{locale:'pt'})//=> 'dezasseis'extenso('1.000.000.000',{locale:'br'})//=> 'um bilhão'extenso('1.000.000.000',{locale:'pt'})//=> 'um bilião'

Define o códigoISO da moeda em que o número deverá ser escrito.

Até o momento são suportadas apenas 9 moedas escolhidas com base na importância econômica e comercial de cada uma delas e que são as mais utilizadas nos países membros daCPLP (Comunidade dos Países de Língua Portuguesa), os quais são: Brasil, Angola, Cabo Verde, Guiné-Bissau, Guiné Equatorial, Moçambique, Portugal, São Tomé e Príncipe e Timor-Leste.

Em breve será suportada a definição de moedas personalizadas. Você pode contribuir enviando umpull request com a adição de uma nova moeda ou com a correção de um erro em uma moeda já existente.

As moedas suportadas são:

• BRL [default] - Real brasileiro
• AOA - Kwanza angolano
• CVE - Escudo cabo-verdiano
• XOF - Franco CFA de África Ocidental
• MZN - Metical moçambicano
• EUR - Euro
• STN - Dobra de São Tomé e Príncipe
• USD - Dólar americano
• MOP - Pataca de Macau

Exemplos:

extenso('42',{mode:'currency'})//=> 'quarenta e dois reais'extenso('42',{mode:'currency',currency:{code:'BRL'}})//=> 'quarenta e dois reais'extenso('42',{mode:'currency',currency:{code:'EUR'}})//=> 'quarenta e dois euros'extenso('42',{mode:'currency',currency:{code:'CVE'}})//=> 'quarenta e dois escudos'

Define a flexão de gênero do número que será escrito.

Atualmente na língua portuguesasomente os números 1 e 2 podem ser escritos tanto no modo masculino quanto no modo feminino, por exemplo,1 pode ser escrito comoum ouuma e2 pode ser escrito comodois ouduas. Caso você precise que o número esteja escrito no gênero feminino, pode usarfemale para defini-lo.

• male [default] - Para escrever no modo masculino.
• female - Para escrever no modo feminino.

Exemplos:

extenso('42')//=> 'quarenta e dois'extenso('42',{number:{gender:'male'}})//=> 'quarenta e dois'extenso('42',{number:{gender:'female'}})//=> 'quarenta e duas'

O idioma padrão do Extenso.js é o Português Brasileiro. Esta escolha se deve a vários fatores:

1. Origem do Projeto: O Extenso.js foi criado no Brasil, onde a necessidade de converter números para texto em português é bastante comum em diversas aplicações.
2. População Falante: O Brasil possui a maior população de falantes de português no mundo, o que torna o Português Brasileiro a variante mais amplamente utilizada do idioma.
3. Moeda Utilizada: Embora o Euro seja uma moeda importante globalmente, o Real (BRL) é a moeda mais utilizada pelos falantes de português, especialmente no Brasil.
4. Separador Decimal: A vírgula é usada como separador decimal na maioria dos países de língua portuguesa, incluindo o Brasil, o que justifica sua adoção como padrão no Extenso.js.

Esses fatores contribuem para que o Português Brasileiro seja o idioma padrão do Extenso.js, garantindo que a biblioteca atenda às necessidades da maioria dos seus usuários.

Você é de Portugal, Angola, Moçambique ou de qualquer outro país onde se fala português? Percebeu alguma diferença na forma como os números são escritos no seu país? Caso tenha identificado variações, abra uma issue para discutirmos como adaptar essas características ao projeto e torná-lo mais completo.

Se encontrou algum erro ou algo que possa ser aprimorado, há diferentes formas de contribuir:

• Abrindo uma issue para relatar sugestões ou problemas.
• Enviando um pull request com melhorias.
• Comentando diretamente no trecho do código que pode ser aprimorado.

Toda contribuição é bem-vinda.

Criado e mantido porMatheus Alves.

Licenciado sob a licençaMIT © 2015-2025