From ba731e428471f153aa24e0a8b2050a1c84b9d074 Mon Sep 17 00:00:00 2001 From: Leonid Vinogradov Date: Sat, 20 Jan 2024 21:03:40 +0300 Subject: [PATCH] [ru] update `Web/JavaScript/Reference/Global_Objects/String/localeCompare` translation (#17979) [ru] update 'Web/JavaScript/Reference/Global_Objects/String/localeCompare' translation --- .../date/tolocaledatestring/index.md | 8 +- .../string/localecompare/index.md | 103 +++++++++++++----- 2 files changed, 82 insertions(+), 29 deletions(-) diff --git a/files/ru/web/javascript/reference/global_objects/date/tolocaledatestring/index.md b/files/ru/web/javascript/reference/global_objects/date/tolocaledatestring/index.md index 96b032c8a098b2..eedecefa146815 100644 --- a/files/ru/web/javascript/reference/global_objects/date/tolocaledatestring/index.md +++ b/files/ru/web/javascript/reference/global_objects/date/tolocaledatestring/index.md @@ -41,7 +41,7 @@ toLocaleDateString(locales, options) ## Примеры -### Пример: использование метода `toLocaleDateString()` +### Использование метода `toLocaleDateString()` При базовом использовании без указания локали возвращается строка, отформатированная в соответствии с локалью и опциями по умолчанию. @@ -51,12 +51,12 @@ var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0)); // Вывод toLocaleDateString() без аргументов зависит от реализации, // локали по умолчанию и часового пояса по умолчанию console.log(date.toLocaleDateString()); -// → "12/11/2012", если код запущен с локалью en-US и часовым поясом America/Los_Angeles +// "12/11/2012", если код запущен с локалью en-US и часовым поясом America/Los_Angeles ``` -### Пример: проверка поддержки аргументов `locales` и `options` +### Проверка поддержки параметров `locales` и `options` -Аргументы `locales` и `options` поддерживаются ещё не всеми браузерами. Для проверки того, поддерживает ли их уже реализация, можно затребовать несуществующую метку языка и проверить, будет ли выброшено исключение {{jsxref("Global_Objects/RangeError", "RangeError")}}: +Параметры `locales` и `options` поддерживаются ещё не всеми браузерами. Для проверки того, поддерживает ли их уже реализация, можно затребовать несуществующую метку языка и проверить, будет ли выброшено исключение {{jsxref("Global_Objects/RangeError", "RangeError")}}: ```js function toLocaleDateStringSupportsLocales() { diff --git a/files/ru/web/javascript/reference/global_objects/string/localecompare/index.md b/files/ru/web/javascript/reference/global_objects/string/localecompare/index.md index e83dc07cf1e941..f59dad646760d8 100644 --- a/files/ru/web/javascript/reference/global_objects/string/localecompare/index.md +++ b/files/ru/web/javascript/reference/global_objects/string/localecompare/index.md @@ -1,57 +1,101 @@ --- title: String.prototype.localeCompare() slug: Web/JavaScript/Reference/Global_Objects/String/localeCompare +l10n: + sourceCommit: b7ca46c94631967ecd9ce0fe36579be334a01275 --- -{{JSRef("Global_Objects", "String")}} +{{JSRef}} -## Сводка +Метод **`localeCompare()`** {{jsxref("String", "строковых значений")}} возвращает число, указывающее, где должна находиться при сортировке (до, после или в том же самом месте, что и строка, переданная в качестве параметра). В реализациях с поддержкой [`Intl.Collator` API](/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator) этот метод просто вызывает `Intl.Collator`. -Метод **`localeCompare()`** возвращает число, указывающее, должна ли данная строка находиться до, после или в том же самом месте, что и строка, переданная через параметр, при сортировке этих строк. +При сравнении большого количества строк, например при сортировке больших массивов, лучше создать объект {{jsxref("Intl.Collator")}} и использовать предоставляемый им метод {{jsxref("Intl/Collator/compare", "compare()")}}. -Новые аргументы `locales` и `options` позволяют приложениям определять язык, чей порядок сортировки оно хочет использовать и настраивать поведение этой функции. В старых реализациях, игнорирующих аргументы `locales` и `options`, используемая локаль и порядок сортировки целиком зависят от реализации. +{{EmbedInteractiveExample("pages/js/string-localecompare.html")}} ## Синтаксис -``` -str.localeCompare(compareString[, locales[, options]]) +```js-nolint +localeCompare(compareString) +localeCompare(compareString, locales) +localeCompare(compareString, locales, options) ``` ### Параметры -Проверьте раздел [Совместимость с браузерами](#Browser_compatibility), чтобы увидеть, какие браузеры поддерживают аргументы `locales` и `options`, и [Пример: проверка поддержки аргументов `locales` и `options`](#Example:_Checking_for_support_for_locales_and_options_arguments) для определения этой возможности. +Параметры `locales` и `options`Параметры `locales` и `options` изменяют поведение функции и позволяют приложениям определять язык, правила форматирования которого, следует использовать. + +В реализациях, поддерживающих [`Intl.Collator` API](/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator), эти параметры соответствуют параметрам конструктора [`Intl.Collator()`](/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator). Реализации без поддержки `Intl.Collator` должны игнорировать оба параметра, возвращаемый результат сравнения полностью зависит от реализации. - `compareString` - - : Строка, с которой сравнивается данная. + - : Строка, с которой сравнивается `referenceStr`. Все значения [приводятся к строкам](/ru/docs/Web/JavaScript/Reference/Global_Objects/String#string_coercion), поэтому отсутствие значения или значение `undefined` приводит к тому, что `localeCompare()` будет сравнивать со строкой `"undefined"`, а это скорее всего не то, что вы ожидаете. +- `locales` {{optional_inline}} + + - : Строка с языковым тегом BCP 47 или массив таких строк. Соответствует параметру [`locales`](/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#locales) конструктора `Intl.Collator()`. + + В реализациях без поддержки `Intl.Collator` этот параметр игнорируется и обычно используется локаль устройства. + +- `options` {{optional_inline}} + + - : Объект определяющий выходной формат. Соответствует параметру [`options`](/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options) конструктора `Intl.Collator()`. -{{page('/ru/docs/Web/JavaScript/Reference/Global_Objects/Collator', 'Parameters')}} + В реализациях без поддержки `Intl.Collator` этот параметр игнорируется. + +Смотрите описание [конструктора `Intl.Collator()`](/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) для подробностей использования параметров `locales` и `options`. + +### Возвращаемое значение + +**Отрицательное** число если `referenceStr` встречается перед `compareString`; **положительное** если `referenceStr` встречается после `compareString`; `0` если они одинаковы. + +В реализациях с поддержкой `Intl.Collator` результат эквивалентен результату вызова `new Intl.Collator(locales, options).compare(referenceStr, compareString)`. ## Описание -Возвращает число, указывающее, должна данная строка находится до, после или в том же самом месте, что и строка, переданная через параметр, при сортировке этих строк. Если данная строка предшествует строке `compareString`, возвращает отрицательное число, если она следует за строкой `compareString`, возвращает положительное значение и возвращает 0, если строки находятся на одном уровне. +Возвращает число, указывающее, расположена ли `referenceStr` до, после или в том же самом месте, что и `compareString`. + +- Отрицательное число, когда `referenceStr` встречается перед `compareString`, +- Положительное число, когда `referenceStr` встречается после `compareString`, +- Возвращает `0` если строки одинаковы. + +> **Предупреждение:** Не полагайтесь на точные значения `-1` и `1`! +> +> Отрицательные и положительные ответы отличаются в зависимости от браузера (и версии браузера), потому что спецификация ECMAScript определяет только то, что числа должны быть положительными и отрицательными. Некоторые браузеры могут возвращать `-2` или `2` или другие значения. ## Примеры -### Пример: использование метода `localeCompare()` +### Использование `localeCompare()` + +```js +// Буква "а" идёт перед "в", поэтому результат будет отрицательным +"а".localeCompare("в"); // -2 или -1 (или другое отрицательное число) + +// В алфавитном порядке слово "первый" идёт после "второй", поэтому результат будет положительным +"первый".localeCompare("второй"); // 2 или 1 (или другое положительное число) + +// "а" и "а" одинаковы, поэтому результат будет равен нулю +"а".localeCompare("а"); // 0 +``` -Следующий пример демонстрирует различные потенциальные результаты для строки, находящейся до, после или на том же самом уровне, что и другая строка: +### Сортировка массива + +`localeCompare()` даёт возможность регистронезависимой сортировки массивов. ```js -console.log(new Intl.Collator().compare("a", "c")); // -2, -1 или другое отрицательное значение -console.log(new Intl.Collator().compare("c", "a")); // 2, 1 или другое положительное значение -console.log(new Intl.Collator().compare("a", "a")); // 0 +const items = ["réservé", "Premier", "Cliché", "communiqué", "café", "Adieu"]; +items.sort((a, b) => a.localeCompare(b, "fr", { ignorePunctuation: true })); +// ['Adieu', 'café', 'Cliché', 'communiqué', 'Premier', 'réservé'] ``` -Обратите внимание, что результат, показанный в коде выше, может сильно различаться в зависимости от браузера и его версии. Происходит это потому, что возвращаемые значения зависят от реализации. То есть, спецификация требует только того, чтобы значение было отрицательным, если строка данная следует до переданной, и положительным — если после. +### Проверка поддержки параметров `locales` и `options` -### Пример: проверка поддержки аргументов `locales` и `options` +Параметры `locales` и `options` поддерживаются ещё не всеми браузерами. -Аргументы `locales` и `options` поддерживаются ещё не всеми браузерами. Для проверки того, поддерживает ли их уже реализация, можно затребовать несуществующую метку языка и проверить, будет ли выброшено исключение {{jsxref("Global_Objects/RangeError", "RangeError")}}: +Чтобы проверить их поддержку реализацией, используйте аргумент `"i"` (требование, чтобы недопустимые языковые метки отклонялись) и исключение {{jsxref("RangeError")}}: ```js function localeCompareSupportsLocales() { try { - "a".localeCompare("b", "i"); + "foo".localeCompare("bar", "i"); } catch (e) { return e.name === "RangeError"; } @@ -59,18 +103,18 @@ function localeCompareSupportsLocales() { } ``` -### Пример: использование аргумента `locales` +### Использование параметра `locales` -Результаты, предоставляемые методом `localeCompare()`, сильно различаются в зависимости от языка. Для получения порядка сортировки языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, несколько запасных языков) через аргумент `locales`: +Результаты, предоставляемые `localeCompare()`, отличаются в зависимости от языка. Для получения порядка сортировки языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, несколько запасных языков) используя параметр `locales`: ```js console.log("ä".localeCompare("z", "de")); // отрицательное значение: в немецком буква ä идёт рядом с буквой a console.log("ä".localeCompare("z", "sv")); // положительное значение: в шведском буква ä следует после буквы z ``` -### Пример: использование аргумента `options` +### Использование параметра `options` -Результат, предоставляемый методом `localeCompare()`, может быть настроен с помощью аргумента `options`: +Результат, предоставляемый `localeCompare()`, может быть настроен с помощью параметра `options`: ```js // В немецком буква a является базовой для буквы ä @@ -80,9 +124,18 @@ console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0 console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // положительное значение ``` -## Производительность +### Сортировка чисел + +```js +// По умолчанию, "2" > "10" +console.log("2".localeCompare("10")); // 1 -При сравнении большого количества строк, например, при сортировке больших массивов, лучшим вариантом будет создание объекта {{jsxref("Global_Objects/Collator", "Intl.Collator")}} и использование функции, предоставляемой его свойством {{jsxref("Collator.prototype.compare", "compare")}}. +// Сортировка чисел с использованием настроек: +console.log("2".localeCompare("10", undefined, { numeric: true })); // -1 + +// Сортировка чисел с использованием языковых меток: +console.log("2".localeCompare("10", "en-u-kn-true")); // -1 +``` ## Спецификации