Number.prototype.toLocaleString()
=================================

O método **`toLocaleString()`** retorna uma string com uma representação sensível a linguagem deste número.

Os novos argumentos `locales` e `options` 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 `locales` e `options` arguments, a localização utilizada e a forma de retornar a string erão totalmente dependente da implementação.

Sintaxe
-------
```

numObj.toLocaleString([locales [, options]])
```

### Parâmetros

Dê uma olhada na seção Compatibilidade do Navegador para verificar quais navegadores suportam os argumentos `locales` e `options`, e o Exemplo: Verificando o suporte dos argumentos `locales` e `options` para detecção desta característica.

**Nota:** ECMAScript Internationalization API, implementada com o Firefox 29, incluiu o argumento `locales` ao método `Number.toLocaleString()`. Se o argumento for `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 Árabe Ocidental. Esta mudança foi relatada como uma regressão que afeta a retrocompatibilidade que será corrigida em breve. (Erro do Firefox 999003)

`locales`

Opcional. Uma string com uma tag de linguagem BCP 47 ou uma matriz delas. Para a forma geral e interpretação do argumento `locales`, veja Intl page. A seguinte chave extendida Unicode é permitida:

`nu`

O sistema de numeração que será usado. Os valores permitidos são: `"arab"`, `"arabext"`, `"bali"`, `"beng"`, `"deva"`, `"fullwide"`, `"gujr"`, `"guru"`, `"hanidec"`, `"khmr"`, `"knda"`, `"laoo"`, `"latn"`, `"limb"`, `"mlym"`, `"mong"`, `"mymr"`, `"orya"`, `"tamldec"`, `"telu"`, `"thai"`, `"tibt"`.


`options`

Opcional. Um objeto com alguns ou todas as seguintes propriedades:

`localeMatcher`

O algoritmo de comparação de localização para utilizar. Os valores permitidos são `"lookup"` e `"best fit"`; o padrão é `"best fit"`. Para mais informações sobre esta opção, veja Intl page.

`style`

O estilo do formato a ser utilizado. Os valores permitidos são `"decimal"` para formato de número simples, `"currency"` para formato monetário e `"percent"` para formato percentual; o padrão é `"decimal"`.

`currency`

A moeda para usar na formatação monetária. Os valores permitidos são os códigos de moedas da ISO 4217, como `"USD"` para dólar estadunidense, `"EUR"` para euro, ou `"CNY"` para RMB chinês — veja a Lista de códigos de moedas e fundos atuais. Não há valor padrão; se o `style` for `"currency"`, a propriedade `currency` deverá ser informada.

`currencyDisplay`

Como será mostrada a moeda na formatação monetária. Os valores permitidos são `"symbol"` para usar um símbolo de moeda localizado como €, `"code"` para usar o código de moeda ISO, `"name"` para usar o nome da moeda localizado como `"dollar"`; o padrão é `"symbol"`.

`useGrouping`

Se usar separadores de agrupamento, como separadores de milhares ou milhares/cem mil/dez milhões. Os valores permitidos são `true` e `false`; o padrão é `true`.

As próximas propriedades se dividem em dois grupos: `minimumIntegerDigits`, `minimumFractionDigits`, e `maximumFractionDigits` no primeiro grupo, `minimumSignificantDigits` and `maximumSignificantDigits` em outro. Se pelo menos uma propriedade do segundo grupo for informado, então o primeiro grupo é ignorado.

`minimumIntegerDigits`

A quantidade mínima de dígitos inteiros para utilizar. É possível usar valores de 1 a 21; o padrão é 1.

`minimumFractionDigits`

A quantidade mínima de dígitos fracionados para utilizar. É possível usar valores de 0 a 20; o padrão para formatos de números simples e percentuais é 0; o padrão para formatos monetários é a menor unidade de dígitos fornecidos pela lista de códigos de moedas ISO 4217 (2 se a lista não fornecer a informação).

`maximumFractionDigits`

O número máximo de dígitos fracionados para utilizar. É possível usar valores de 0 a 20; o padrão para a formatação de número simples é o maior entre `minimumFractionDigits` e 3; o padrão para formatos monetários é o maior número de dígitos entre `minimumFractionDigits` e o fornecido pela lista de códigos de moedas ISO 4217 (2 se a lista não fornecer a informação); o padrão para a formatação percentual é o maior número entre `minimumFractionDigits` e 0.

`minimumSignificantDigits`

A quantidade mínima de dígitos significantes para usar. Os valores permitidos são de 1 a 21; o padrão é 1.

`maximumSignificantDigits`

A quantidade máxima de dígitos significantes para usar. Os valores permitidos são de 1 a 21; o padrão é `minimumSignificantDigits`.


Exemplos
--------

### Usando `toLocaleString`

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.


```js
var numero = 3500;

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

### Verificando o suporte dos argumentos `locales` e `options`

Os argumentos `locales` e `options` 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 `RangeError` (en-US) pode ser usada da seguinte forma:


```js
function toLocaleStringSupportsLocales() {
  var numero = 0;
  try {
    numero.toLocaleString("i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}
```


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

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 `Number.prototype.toLocaleString` diretamente:


```js
function toLocaleStringSupportsOptions() {
  return !!(
    typeof Intl == "object" &&
    Intl &&
    typeof Intl.NumberFormat == "function"
  );
}
```


Estes testes para um objeto `Intl` global, verifica se ele não é `null` e se uma propriedade `NumberFormat` é uma função.

### Usando `locales`

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 `locales`:


```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 Árabes Orientais 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
```

### Usando `options`

Os resultados obtidos por `toLocaleString` pode ser personalizado usando o argumento `options`:


```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
```

Desempenho
----------

Quando formatar uma grande quantidade de números, é melhor criar um objeto `NumberFormat` e usar a função fornecida pela propriedade `NumberFormat.format` (en-US).

Especificações
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.tolocalestring |
| ECMAScript Internationalization API Specification # sup-number.prototype.tolocalestring |

Compatibilidade com navegadores
-------------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `Number.prototype.toString()`