Сообщения в React

Храните исходный текст и контекст в компонентах, а переводы выводите из каталогов — с подстановкой значений, учётом грамматики и элементами React.

Сообщение компонента должно быть рядом с действием, которое оно поясняет. «Сохранить» в форме означает отправку изменений, а в статье — добавление в закладки. Когда исходный текст и его смысл хранятся вместе, переводчики видят эту разницу, а разработчики понимают, как работает компонент, без поиска ключа в другом файле.

@lingo.dev/react использует явные вызовы сообщений:

tsx
import { useLingo } from "@lingo.dev/react";

export function SaveButton() {
  const l = useLingo();
  return <button type="submit">{l.text("Save", { context: "Submit changes to account settings" })}</button>;
}

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

От компонента к другому языку #

Сначала выведите локальный перевод. Небольшой каталог наглядно покажет, как работает поиск перевода, без учётной записи и сетевых запросов.

В рабочем процессе приложения lingo extract собирает распознаваемые вызовы в исходный каталог JSONC и генерирует объявления TypeScript. CLI отправляет этот файл на перевод и получает файл для целевой локали. Загрузчик преобразует его в набор соответствий между ключами и строками для провайдера. В разделе «Извлечение и загрузка каталогов» описан весь процесс, в том числе как сохранить активные сообщения, если в переведённом JSONC больше нет комментариев с метаданными.

Отрисовка выполняется локально. Среда выполнения не обращается к движку локализации и не содержит ключа API. Перевод на сервере выполняйте через интеграцию с API, а готовые каталоги передавайте приложению при обычной сборке или загрузке данных по запросу.

Пишите сообщения, которые нужны читателю #

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

Что нужно в сообщенииЧто использовать
Обычный текст с подстановкой значенийl.text.
Ссылки, выделение или другой элемент Reactl.rich с именованными функциями обратного вызова для отрисовки.
Грамматические формы, зависящие от количества, или выбор по категорииl.plural и l.select.
Числа, даты, списки или операции с текстом с учётом локалиМетоды форматирования, которые используют встроенный Intl.

В справочнике по провайдеру и хукам описаны вложенные каталоги и createLingo для кода вне компонентов. Раздел «Метаданные локали» содержит сведения о направлении письма, письменности и регионе, которые помогают выбрать подходящие настройки документа и макета.

Свяжите сообщения с остальным приложением #

Адаптеры Next.js Pages и TanStack Start связывают каталоги с соответствующими системами маршрутизации. В других конфигурациях загружайте локаль и сообщения до отрисовки и сохраняйте эту пару при серверной отрисовке и гидратации.

Используйте сгенерированные типы, чтобы находить ошибки в исходном тексте, контексте и значениях во время редактирования. Тесты отрисовки помогут проверить шаблоны, которые действительно загружены. Если перевод не появляется, раздел «Устранение неполадок» поможет проследить его поиск от компонента до каталога.

Экспорты #

Корневой модуль экспортирует LingoProvider, useLingo, createLingo и computeKey, а также типы LingoProviderProps, Lingo, Messages, LingoMessages, MessageKey, TextOptions, RichOptions, PluralForms, SelectForms и FormatMethods. Отдельная точка входа @lingo.dev/react/testing экспортирует withLingo и renderStatic.