toLocaleString() - метод для преобразования массива в локализованную строку в JavaScript

toLocaleString() преобразует массив в строку с учётом локали.

Главная идея метода в том, что он вызывает toLocaleString() у каждого элемента массива и собирает общий результат в одну строку.

Синтаксис

array.toLocaleString()
array.toLocaleString(locales)
array.toLocaleString(locales, options)

locales - локаль или список локалей, например "ru-RU" или "en-US".

options - дополнительные настройки форматирования.

Что делает toLocaleString()

Метод берёт каждый элемент массива, преобразует его в локализованную строку и соединяет результаты в один текст.

const numbers = [1234.56, 7890.12];

console.log(numbers.toLocaleString("ru-RU"));

Для чисел и дат результат обычно выглядит иначе, чем у обычного toString().

Что возвращает toLocaleString()

toLocaleString() всегда возвращает строку.

const values = [1000, 2000];
const result = values.toLocaleString("en-US");

console.log(result);        // "1,000,2,000" или похожий формат
console.log(typeof result); // "string"

Это главное, что важно запомнить: результатом будет строка, а не массив.

Локаль влияет на формат

Для чисел разница особенно заметна.

const values = [123456.78];

console.log(values.toLocaleString("en-US")); // "123,456.78"
console.log(values.toLocaleString("ru-RU")); // "123 456,78"

Один и тот же массив может дать разный результат в зависимости от локали.

Пример с датами

toLocaleString() полезен и для массива дат.

const dates = [new Date("2025-01-01T12:00:00Z")];

console.log(dates.toLocaleString("ru-RU"));
console.log(dates.toLocaleString("en-US"));

У даты результат тоже зависит от выбранной локали.

options передаются дальше элементам

Если в массиве лежат числа или даты, через options можно настроить формат.

const prices = [1234.5, 67.89];

console.log(
  prices.toLocaleString("ru-RU", {
    style: "currency",
    currency: "RUB",
  }),
);

Это особенно полезно для денег, дат и времени.

Исходный массив не меняется

toLocaleString() только возвращает строку и не изменяет сам массив.

const numbers = [1000, 2000];
const result = numbers.toLocaleString("en-US");

console.log(numbers); // [1000, 2000]
console.log(result);  // строка

null, undefined и пустые слоты

null, undefined и пустые слоты дают пустые участки строки.

const values = [1, null, undefined, 4];

console.log(values.toLocaleString("ru-RU"));

Как и у toString(), в результате между позициями могут остаться только разделители.

Вложенные массивы

Если внутри есть вложенные массивы, у них тоже будет вызван toLocaleString().

const values = [[1000, 2000], [3000]];

console.log(values.toLocaleString("en-US"));

Из-за этого итоговая строка может выглядеть неочевидно, особенно при сложной вложенности.

Обычные объекты

Если в массиве лежат обычные объекты, результат зависит от того, как у них устроен toLocaleString().

const values = [{ name: "Anna" }];

console.log(values.toLocaleString()); // "[object Object]"

Для обычных объектов такой результат обычно не слишком полезен.

Разделитель может отличаться

Элементы в итоговой строке разделяются запятой или похожим локальным разделителем.

Важно не полагаться на точный вид разделителя во всех окружениях.

const values = [1234.56, 7890.12];

console.log(values.toLocaleString("ru-RU"));

Результат может немного отличаться в зависимости от среды выполнения.

toLocaleString() и toString()

toString() не учитывает локаль.

toLocaleString() делает это.

const values = [123456.78];

console.log(values.toString());              // "123456.78"
console.log(values.toLocaleString("ru-RU")); // "123 456,78"

Если нужна локализация, обычно используют именно toLocaleString().

toLocaleString() и join()

join() просто соединяет элементы через заданный разделитель.

toLocaleString() сначала форматирует каждый элемент с учётом локали.

const values = [1234.56, 7890.12];

console.log(values.join(" | "));
console.log(values.toLocaleString("ru-RU"));

Это разные задачи, хотя обе приводят массив к строке.

Когда это полезно

toLocaleString() удобно использовать, когда:

нужно показать массив чисел в локальном формате
нужно вывести массив дат
важно учитывать язык и регион пользователя

Пример:

const prices = [1234.5, 9876.54];
const text = prices.toLocaleString("ru-RU", {
  style: "currency",
  currency: "RUB",
});

console.log(text);

Частые ошибки

Думать, что toLocaleString() возвращает массив

const result = [1000, 2000].toLocaleString("en-US");

console.log(result); // строка

Это строка, а не массив.

Ждать, что результат всегда выглядит одинаково

const values = [123456.78];

console.log(values.toLocaleString("ru-RU"));
console.log(values.toLocaleString("en-US"));

Результат зависит от локали и иногда от среды выполнения.

Использовать метод для обычных объектов и ждать красивый текст

const values = [{ id: 1 }];

console.log(values.toLocaleString()); // "[object Object]"

Для простых объектов результат обычно не слишком полезен.

Быстрая памятка

toLocaleString() превращает массив в строку с учётом локали
результатом всегда будет string
локаль особенно заметно влияет на числа и даты
исходный массив не меняется
toString() не учитывает локаль, а toLocaleString() учитывает

Коротко

toLocaleString() - это удобный способ получить строку из массива в локализованном формате. Главное, что стоит запомнить: метод вызывает локализованное преобразование для каждого элемента и особенно полезен для чисел и дат.