Сообщения в React
Храните исходный текст и контекст в компонентах, а переводы выводите из каталогов — с подстановкой значений, учётом грамматики и элементами React.
Сообщение компонента должно быть рядом с действием, которое оно поясняет. «Сохранить» в форме означает отправку изменений, а в статье — добавление в закладки. Когда исходный текст и его смысл хранятся вместе, переводчики видят эту разницу, а разработчики понимают, как работает компонент, без поиска ключа в другом файле.
@lingo.dev/react использует явные вызовы сообщений:
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. |
| Ссылки, выделение или другой элемент React | l.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.