---
title: Number.prototype.toLocaleString()
slug: Web/JavaScript/Reference/Global_Objects/Number/toLocaleString
tags:
  - Internacionalização
  - JavaScript
  - Método(2)
  - Number
  - Número
  - Prototype
translation_of: Web/JavaScript/Reference/Global_Objects/Number/toLocaleString
---
<div>{{JSRef}}</div>

<p>O método <strong><code>toLocaleString()</code></strong> retorna uma string com uma representação sensível a linguagem deste número.</p>

<p>Os novos argumentos <code>locales</code> e <code>options</code> permitem às aplicações especificar a linguagem cujas convenções de formatações serão utilizadas e personalizar o comportamento da função. Nas implementações anteriores, que ignorava os argumentos <code>locales</code> e <code>options</code> arguments, a localização utilizada e a forma de retornar a string erão totalmente dependente da implementação.</p>

<h2 id="Sintaxe">Sintaxe</h2>

<pre class="syntaxbox"><code><em>numObj</em>.toLocaleString(</code><code>[locales [, options]])</code></pre>

<h3 id="Parâmetros">Parâmetros</h3>

<p>Dê uma olhada na seção <a href="#Browser_compatibility">Compatibilidade do Navegador</a> para verificar quais navegadores suportam os argumentos <code>locales</code> e <code>options</code>, e o <a href="#">Exemplo: Verificando o suporte dos argumentos <code>locales</code> e <code>options</code></a> para detecção desta característica.</p>

<div class="note">
<p><strong>Nota:</strong> ECMAScript Internationalization API, implementada com o Firefox 29, incluiu o argumento <code>locales</code> ao método <code>Number.toLocaleString()</code>. Se o argumento for {{jsxref("undefined")}}, este método retorna os dígitos de localização especificados pelo SO, enquanto que as versões anteriores doFirefox retornavam os dígitos<a href="https://en.wikipedia.org/wiki/Arabic_numerals"> Árabe Ocidental</a>. Esta mudança foi relatada como uma regressão que afeta a retrocompatibilidade que será corrigida em breve. ({{bug(999003)}})</p>
</div>

<div>{{page('pt-BR/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat', 'Parâmetros')}}</div>

<h2 id="Exemplos">Exemplos</h2>

<h3 id="Usando_toLocaleString">Usando <code>toLocaleString</code></h3>

<p>No uso básico sem a especificação de uma localização, o método retornará uma string formatada com a localização e as opções padrão.</p>

<pre class="brush: js">var numero = 3500;

console.log(numero.toLocaleString()); // Mostra "3,500" se a localização for U.S. English
</pre>

<h3 id="Verificando_o_suporte_dos_argumentos_locales_e_options">Verificando o suporte dos argumentos <code>locales</code> e <code>options</code></h3>

<p>Os argumentos <code>locales</code> e <code>options</code> não são suportados por todos os navegadores ainda. Para verificar pelo suporte das implementações do ES5.1 e posteriores, a requisição de tags de linguagem ilegais são rejeitadas com uma exceção {{jsxref("Global_Objects/RangeError", "RangeError")}} pode ser usada da seguinte forma:</p>

<pre class="brush: js">function toLocaleStringSupportsLocales() {
  var numero = 0;
  try {
     numero.toLocaleString('i');
  } catch (e) {
    return e.name === 'RangeError';
  }
  return false;
}
</pre>

<p>Antes da ES5.1, implementações que não exigiam um tratamento de erro se <code>toLocaleString</code> fosse chamada com argumentos.</p>

<p>Uma verificação que funciona em todos os casos, incluindo aqueles que suportam ECMA-262 antes da edição 5.1, é testar pelas especificações de característicadas da ECMA-402 que exigem suporte de opções regionais para <code>Number.prototype.toLocaleString</code> diretamente:</p>

<pre class="brush: js">function toLocaleStringSupportsOptions() {
  return !!(typeof Intl == 'object' &amp;&amp; Intl &amp;&amp; typeof Intl.NumberFormat == 'function');
}
</pre>

<p>Estes testes para um objeto <code>Intl</code> global, verifica se ele não é <code>null</code> e se uma propriedade <code>NumberFormat</code> é uma função.</p>

<h3 id="Usando_locales">Usando <code>locales</code></h3>

<p>Este exemplo mostra algumas variações de formatos de números localizados. A fim de obter o formato da linguagem utilizada na interface do usuário da sua aplicação, tenha certeza de especificar a língua (e possivelmente algumas línguas reservas) usando o argumento<code> locales</code>:</p>

<pre class="brush: js">var numero = 123456.789;

// O alemão usa vírgula como separador de decimal e ponto para milhares
console.log(numero.toLocaleString('de-DE'));
// → 123.456,789

// O árabe usa dígitos <a href="https://en.wikipedia.org/wiki/Eastern_Arabic_numerals">Árabes Orientais</a> em muitos países que falam árabe
console.log(numero.toLocaleString('ar-EG'));
// → ١٢٣٤٥٦٫٧٨٩

// A Índia usa separadores de milhares/cem mil/dez milhões
console.log(numero.toLocaleString('en-IN'));
// → 1,23,456.789

// A chave de extensão nu requer um sistema de numeração, ex. decimal chinês
console.log(numero.toLocaleString('zh-Hans-CN-u-nu-hanidec'));
// → 一二三,四五六.七八九

// Quando informada uma língua sem suporte, como balinês,
// inclua uma língua reseva, neste caso indonésio
console.log(numero.toLocaleString(['ban', 'id']));
// → 123.456,789
</pre>

<h3 id="Usando_options">Usando <code>options</code></h3>

<p>Os resultados obtidos por <code>toLocaleString</code> pode ser personalizado usando o argumento<code> options</code>:</p>

<pre class="brush: js">var numero = 123456.789;

// informando um formato de moeda
console.log(numero.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' }));
// → 123.456,79 €

// o yen japonês não tem uma unidade menor
console.log(numero.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' }))
// → ￥123,457

// limitando a três dígitos significativos
console.log(numero.toLocaleString('en-IN', { maximumSignificantDigits: 3 }));
// → 1,23,000
</pre>

<h2 id="Desempenho">Desempenho</h2>

<p>Quando formatar uma grande quantidade de números, é melhor criar um objeto {{jsxref("NumberFormat")}} e usar a função fornecida pela propriedade {{jsxref("NumberFormat.format")}}.</p>

<h2 id="Especificações">Especificações</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Especificação</th>
   <th scope="col">Status</th>
   <th scope="col">Comentário</th>
  </tr>
  <tr>
   <td>{{SpecName('ES3')}}</td>
   <td>{{Spec2('ES3')}}</td>
   <td>Definição inicial. Implementado no JavaScript 1.5.</td>
  </tr>
  <tr>
   <td>{{SpecName('ES5.1', '#sec-15.7.4.3', 'Number.prototype.toLocaleString')}}</td>
   <td>{{Spec2('ES5.1')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-number.prototype.tolocalestring', 'Number.prototype.toLocaleString')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-number.prototype.tolocalestring', 'Number.prototype.toLocaleString')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('ES Int 1.0', '#sec-13.2.1', 'Number.prototype.toLocaleString')}}</td>
   <td>{{Spec2('ES Int 1.0')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('ES Int 2.0', '#sec-13.2.1', 'Number.prototype.toLocaleString')}}</td>
   <td>{{Spec2('ES Int 2.0')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('ES Int Draft', '#sec-Number.prototype.toLocaleString', 'Number.prototype.toLocaleString')}}</td>
   <td>{{Spec2('ES Int Draft')}}</td>
   <td> </td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Compatibilidade com navegadores</h2>

<p>{{Compat("javascript.builtins.Number.toLocaleString")}}</p>

<h2 id="Veja_também">Veja também</h2>

<ul>
 <li>{{jsxref("Number.prototype.toString()")}}</li>
</ul>