i18nSupport
Расширение для Visual Studio Code, которое помогает выносить русские (кириллические) строки из программного кода в отдельные файлы констант. Это первый шаг к локализации (i18n) — после переноса строк в коде остаётся только «скелет» вида StrI18N('ключ'), а сами тексты лежат в const.json, куда их удобно передавать переводчикам.
Как это работает (коротко)
- Вы открываете файл с кодом — расширение подсвечивает все строки, содержащие кириллицу.
- Вы переносите строки в константы (одну или все сразу).
- В коде строка заменяется на вызов
StrI18N('ключ'), а сам текст записывается в const.json.
- Если в коде встречается
StrI18N('ключ'), которого нет в const.json — расширение подсвечивает его красным.
Возможности
Голубая подсветка кириллических строк
Все строковые литералы, содержащие хотя бы одну кириллическую букву, подсвечиваются полупрозрачным голубым фоном. Подсвечиваются:
- обычные строки:
'Привет, мир!', "Ошибка загрузки";
- шаблонные строки без подстановок:
`Список элементов`;
- шаблонные строки с подстановками:
`Всего: ${count} шт.`.
Не подсвечиваются:
- строки, которые уже обёрнуты в
StrI18N(...) или StrFormat(...) — они считаются уже переведёнными;
- комментарии (расширение работает через AST, поэтому комментарии не попадают в список литералов).
Подсветка обновляется на лету при каждом изменении файла.
Красная подсветка отсутствующих констант
Расширение находит все вызовы StrI18N('ключ') в текущем файле и проверяет, есть ли этот ключ в const.json (в папке, выбранной настройкой constantPlace). Если ключа нет — строка подсвечивается красным.
Исключение: Ключи, содержащие подстроку GLOBAL/, не подсвечиваются. Это глобальные константы, которые хранятся в другом месте и не должны присутствовать в локальном const.json.
Подсветка обновляется при изменении файла и при изменении const.json.
Перенос одной строки
Выделяете строку (или шаблонную строку) в редакторе → правая кнопка мыши → «Перенести в константы» (или палитра команд Ctrl+Shift+P → i18n: Перенести в константы).
Что происходит:
- Расширение генерирует ключ из содержимого строки (транслитерация + нормализация).
- Записывает пару
ключ: текст в const.json (создаёт файл и папки, если их ещё нет).
- Заменяет выделенный текст в коде на
StrI18N('ключ') (для обычных строк) или на StrFormat(StrI18N('ключ'), { p0: expr, ... }) (для шаблонных строк с подстановками).
- Если ключ уже существует в
const.json с тем же значением — используется существующий ключ (дубликаты не создаются).
Массовая обработка файла
Команда «Обработать весь файл» (i18n: Обработать весь файл) находит все кириллические литералы в активном файле и переносит их в const.json за один проход. В коде все найденные строки заменяются на соответствующие вызовы StrI18N / StrFormat.
Генерация ключей
Ключ генерируется автоматически из текста строки:
- кириллица транслитерируется в латиницу (а→a, б→b, в→v, …, я→ya);
- латиница и цифры остаются как есть;
- пробелы и спецсимволы заменяются на
_ или удаляются;
- ключ приводится к нижнему регистру;
- длина ограничивается настройкой
maxKeyLength (по умолчанию 50 символов).
Пример: строка "Ошибка загрузки файла" → ключ oshibka_zagruzki_fayla.
Шаблонные строки
Если строка содержит подстановки ${...}, расширение:
- заменяет каждую подстановку на плейсхолдер
{p0}, {p1}, …;
- сохраняет значение в
const.json с плейсхолдерами: "Всего: {p0} шт.";
- в коде формирует вызов:
StrFormat(StrI18N('vsego_p0_sht'), { p0: count }).
Выбор папки хранения констант
Команда «Сменить папку хранения констант» переключает режим:
| Режим |
Путь к const.json |
Когда использовать |
component (по умолчанию) |
<3 уровня вверх от файла>/i18n/<имя_файла>/ru/const.json |
Когда константы лежат в корне компонента |
near |
<папка_с_файлом>/i18n/<имя_файла>/ru/const.json |
Когда константы хранятся рядом с кодом |
Переключение мгновенно влияет на все последующие операции (чтение/запись/подсветка).
Команды
Команда (палитра Ctrl+Shift+P) |
Горячие клавиши |
Что делает |
i18n: Перенести в константы |
ПКМ → контекстное меню (при выделении) |
Переносит выделенную строку в const.json |
i18n: Обработать весь файл |
— |
Массово переносит все кириллические строки активного файла |
i18n: Включить/выключить подсказки |
— |
Вкл/выкл голубую подсветку кириллицы |
i18n: Включить/выключить подсказки отсутствующих констант |
— |
Вкл/выкл красную подсветку |
i18n: Сменить папку хранения констант |
— |
Переключает режим component / near |
Настройки
Все настройки находятся в разделе i18n Extractor (поиск в настройках VS Code: i18nExtractor).
| Параметр |
Тип |
По умолчанию |
Описание |
i18nExtractor.enableHighlighting |
boolean |
false |
Включить голубую подсветку кириллических строк |
i18nExtractor.enableMissingConstHighlight |
boolean |
false |
Включить красную подсветку отсутствующих констант |
i18nExtractor.maxKeyLength |
number |
50 |
Максимальная длина генерируемого ключа (от 3 до 10000) |
i18nExtractor.constantPlace |
string |
"component" |
Где хранить const.json: "component" или "near" |
Где хранятся константы
Файл const.json создаётся автоматически (вместе с папками) при первом переносе. Файл записывается с BOM (UTF-8 с BOM), чтобы корректно открываться в Windows.
Пример содержимого const.json:
{
"oshibka_zagruzki": "Ошибка загрузки",
"vsego_p0_sht": "Всего: {p0} шт.",
"soobshchenie": "Сообщение"
}
Примеры: до / после
Обычная строка:
// ДО
showMessage('Ошибка загрузки файла');
// ПОСЛЕ
showMessage(StrI18N('oshibka_zagruzki_fayla'));
Шаблонная строка с подстановкой:
// ДО
showMessage(`Всего: ${count} элементов`);
// ПОСЛЕ
showMessage(StrFormat(StrI18N('vsego_p0_elementov'), { p0: count }));
Строка, которая уже переведена — не затрагивается:
// Не меняется, не подсвечивается голубым
showMessage(StrI18N('privet'));
