Проверка типов в вызовах сообщений

Создавайте и подключайте объявления, чтобы проверять исходные строки, контексты и значения сообщений во время редактирования.

Вызов сообщения может быть корректным с точки зрения TypeScript, но запрашивать не ту запись каталога. Из-за изменения контекста или опечатки в плейсхолдере на экране может остаться исходный текст или {name}. При извлечении создаются объявления, которые включают известные исходные сообщения в систему типов приложения.

Создайте и подключите файл объявлений #

После установки CLI выполните:

sh
npx lingo extract --src src --source-locale en

По умолчанию создаются файлы locales/en.jsonc и lingo.d.ts. Добавьте lingo.d.ts в существующий список включаемых файлов tsconfig приложения, если ни один из текущих шаблонов не охватывает этот файл. Остальные записи оставьте без изменений:

json
{
  "include": ["src", "lingo.d.ts"]
}

Запустите обычную проверку типов приложения. Если файл объявлений не входит в проект компилятора, объявления не ограничивают вызовы. Если при извлечении используется --types или i18n.typesPath, подключите файл по фактическому пути, куда он записывается.

Что означает сгенерированный интерфейс #

Файл дополняет LingoMessages исходными строками и их параметрами. Вот пример структуры, которая получается при генерации:

ts
export {};

declare module "@lingo.dev/react" {
  interface LingoMessages {
    "Hello, {name}.": {
      values: { name: string | number };
      context: "Greeting on the account dashboard";
    };
    "Save": {
      context: "Submit settings" | "Bookmark an article";
    };
  }
}

Генерируйте этот файл заново, а не обновляйте пример вручную. Теперь для приветствия нужны values.name и контекст, полученный при извлечении. Save принимает любой из записанных контекстов. Исходная строка, которой нет в списке, не соответствует ограничению MessageKey.

Без сгенерированных записей LingoMessages остаётся пустым, а MessageKey допускает любую строку. После заполнения MessageKey становится объединением строковых ключей. Поведение во время выполнения не меняется: эти ограничения действуют на l.text и l.rich только во время редактирования.

Обновляйте типы вместе с исходным кодом #

Повторяйте извлечение после изменения текста, контекста или плейсхолдеров. Удалённые сообщения теряют связь с исходным кодом и исключаются из генерации. Для записи без контекста сигнатура не создаётся, если только другая активная запись для той же исходной строки не содержит контекст. Несколько контекстов для одной исходной строки образуют объединение.

Чтобы проверить актуальность без записи файлов:

sh
npx lingo extract --src src --source-locale en --check

Эта команда сравнивает JSONC и объявления с результатом текущего извлечения. Это локальная проверка, а не запрос на перевод. Запускайте её вместе с проверкой типов, чтобы устаревший файл объявлений не позволял незаметно проверять вызовы по старому набору сообщений.

Типы значений и охват проверки #

Генератор распознаёт аргументы ICU верхнего уровня. Он использует number для аргументов множественного числа, порядковых числительных и чисел, string — для аргументов выбора, Date | number — для аргументов даты и времени, а string | number — для простых плейсхолдеров. Генератор находит не все плейсхолдеры внутри ветвей множественного числа, поэтому отдельно проверяйте значения в этих ветвях с помощью тестов.

Сгенерированные ограничения для исходных строк применяются к text и rich. Вспомогательные функции plural и select сохраняют собственные сигнатуры форм и параметров. Вызовы с форматированием добавляют необязательную карту тегов, но объявления не проверяют расположение тегов в переводе.

Типы показывают, соответствует ли вызов контракту извлечённых исходных сообщений. Тесты рендеринга показывают, может ли загруженный перевод использовать эти значения. Используйте оба вида проверки: даже при корректном вызове нужная запись каталога может отсутствовать, а ICU в переводе — содержать ошибки.