If you don't speak Portuguese, check out the English version of this README here.
Caso queira de uma consultoria particular entre em contato comigo aqui.
-blue.svg){kind=icon}
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 extensoOu se preferir, com Yarn:
yarn add extensoESM:
import extenso from 'extenso'
extenso(123)
//=> 'cento e vinte e três'CommonJS:
const extenso = require('extenso')
extenso(123)
//=> 'cento e vinte e três'TypeScript:
import extenso, { type ExtensoOptions } from 'extenso'
const options: ExtensoOptions = { mode: 'number' }
const result: string = extenso(123, options)Também são exportados os tipos CurrencyOptions, NumberOptions, ExtensoMode, ExtensoLocale, ExtensoScale, ExtensoGender, CurrencyCode e DecimalSeparator.
O pacote requer Node.js 18 ou mais recente.
extenso(number[, options])O valor que deverá ser escrito por extenso (obrigatório).
Entradas number finitas, inclusive quando o JavaScript as representa em notação científica, são aceitas e normalizadas antes da conversão. O valor já precisa ser representável com a precisão desejada pelo tipo number: para inteiros maiores que Number.MAX_SAFE_INTEGER, use string ou bigint. bigint aceita somente inteiros.
Strings preservam todos os dígitos fornecidos. O sinal - só pode aparecer no início. Quando houver agrupamento, o primeiro grupo deve ter de um a três dígitos e os demais exatamente três. O separador decimal precisa ser seguido por dígitos; entradas incompletas como 1. são rejeitadas.
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ções aqui [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.
Por padrão, o ponto é o separador decimal (point) e a vírgula é o separador de milhares. Use comma para inverter essa interpretação. A opção é especialmente importante para strings, pois entradas number são normalizadas diretamente da representação do JavaScript.
Observe que caso o separador decimal seja point (.) então o separador de milhar automaticamente será comma (,) e vice-versa.
point[default] - Para usar ponto como separador (ex.:3.14).comma- Para usar vírgula 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 é escrito dezesseis no Brasil, enquanto em Portugal é escrito dezasseis. A configuração dessas diferenças é feita aqui.
Até o momento, são suportados os dialetos br e pt 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 uma issue 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ódigo ISO 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 da CPLP (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 um pull 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 brasileiroAOA- Kwanza angolanoCVE- Escudo cabo-verdianoXOF- Franco CFA de África OcidentalMZN- Metical moçambicanoEUR- EuroSTN- Dobra de São Tomé e PríncipeUSD- Dólar americanoMOP- 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.
O gênero feminino flexiona unidades, dezenas e centenas (uma, duas, duzentas, trezentas etc.), inclusive no grupo dos milhares. Os nomes de escala como milhão e bilhão permanecem masculinos.
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'
extenso('322000', { number: { gender: 'female' } })
//=> 'trezentas e vinte e duas mil'No modo currency, são aceitas zero, uma ou duas casas decimais. Uma casa é completada com zero à direita (1.1 equivale a dez centavos). Mais de duas casas são rejeitadas sem truncamento ou arredondamento. Códigos e símbolos podem aparecer antes ou depois do valor; marcadores de moedas diferentes na mesma entrada são considerados ambíguos e geram erro. currency.code tem prioridade sobre uma única moeda detectada.
mode, locale, scale, decimalSeparator, number.gender e currency.code são validados em runtime. A biblioteca também rejeita entrada vazia, sinal isolado, agrupamento inválido, decimal incompleto, NaN, infinitos, moedas conflitantes, valores acima da escala escolhida e strings com mais de 1000 caracteres.
Esta preparação inclui mudanças incompatíveis: CommonJS agora retorna a função diretamente; formatos numéricos anteriormente tolerados podem gerar erro; moeda não aceita mais de duas casas; e opções desconhecidas não usam valores padrão silenciosamente. A próxima versão ainda não foi publicada e seu número será decidido pelo mantenedor.
O idioma padrão do Extenso.js é o Português Brasileiro. Esta escolha se deve a vários fatores:
- 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.
- 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.
- 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.
- Separador Decimal: A opção
decimalSeparatorpermite escolher explicitamente ponto ou vírgula sem alterar o dialeto de saída.
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 por Matheus Alves.
Licenciado sob a licença MIT © 2015-2025