Как устранить проблемы с сообщениями в React
Найдите, на каком этапе между извлечением и рендерингом сообщение теряет перевод, значения, теги или локаль.
Проследите путь сообщения, которое вы видите на экране. Его исходный текст и контекст определяют ключ. Ближайший провайдер передаёт каталог, а выбранный шаблон форматируется со значениями из вызова. Проверка этих данных обычно помогает найти причину сбоя, не меняя сгенерированные ключи вручную.
useLingo вызывает исключение вне провайдера #
Разместите LingoProvider выше компонента, который вызывает хук, в том числе в тестах и изолированных предпросмотрах. Если компонент сам возвращает провайдер, этот провайдер находится ниже хука. Перенесите хук в дочерний компонент или используйте createLingo(locale, messages) в функции, которая не использует контекст React для рендеринга.
Для текущей реализации провайдера используйте React 19. Более широкий диапазон версий в peer-зависимостях пакета не делает сокращённый синтаксис контекста React 19 совместимым с React 18.
Вместо перевода появляется исходный текст #
- Проверьте, какие
localeиmessagesфактически получает ближайший провайдер. Сообщения должны быть объектом с хешами в качестве ключей и строками в качестве значений, а не URL файла, промисом илиLocaleFile. - Вычислите
computeKey(source, context)для точного вызова и найдите этот ключ в переданном объекте. Изменения в пунктуации, пробельных символах или контексте могут создать новый ключ. - Если в результатах извлечения нет ключа, задайте исходный текст и контекст литералами, используйте поддерживаемый получатель вызова, например
l.text(...), и повторите извлечение. Вызов с вычисляемыми данными может работать при рендеринге, но не поддаваться извлечению. - Если ключ есть в исходном каталоге, но отсутствует в целевом, получите готовый перевод и заново загрузите объект с сообщениями. Сама отправка на перевод не добавляет файл в приложение.
- Если ключ есть в файле, но провайдер его не получает, проверьте пути загрузчика и выбор маршрута. В разделе Загрузка каталогов показано, как объединить данные по исходным ключам, если в переведённом JSONC потеряны метаданные.
Если значение отсутствует или содержит пустую строку, вместо него используется исходный текст. Предупреждения в режиме разработки различают эти случаи и не повторяются для одной и той же пары ключа и локали. В рабочей среде эта диагностика отключена, поэтому отсутствие сообщений в консоли не подтверждает полноту каталога.
Загрузчик Next возвращает {}, если файл отсутствует, но может вызвать исключение при некорректном JSONC. Встроенный каталог TanStack при отсутствии файла, ошибке загрузки или разбора возвращает {} и кеширует результат. В обоих случаях подстановка исходного текста сохраняет читаемость страницы, но может скрыть проблему с загрузкой.
В тексте остаётся плейсхолдер или выражение ICU #
Проверьте объект values, который передаётся в вызов. Если значений для простых подстановок нет, в тексте остаётся {name}. Без объекта значений среда выполнения возвращает выбранный шаблон без форматирования.
Для сложного сообщения ICU проверьте синтаксис выбранного шаблона перевода, имена аргументов и типы значений. При ошибке разбора или форматирования возвращается тот же шаблон, а в режиме разработки выводится сообщение об ошибке без повторов. Поэтому на экране может появиться некорректный перевод вместо английского исходного текста. Исправьте шаблон или передайте недостающий аргумент, затем повторите рендеринг для этого случая.
Сгенерированные объявления помогают выявить проблемы с обнаруженными аргументами исходного текста, но не проверяют синтаксис перевода и не находят все плейсхолдеры внутри ветки ICU. Проверьте нужную ветку с реальными значениями.
Ссылка исчезает или теги появляются как текст #
Сообщения с разметкой используют именованные функции обратного вызова, например tags.link. Имя должно точно совпадать с именем тега в переводе, а адрес ссылки должен оставаться в функции обратного вызова. Неизвестные парные теги, самозакрывающиеся теги и открывающие теги без закрывающих остаются обычным текстом.
Используйте разные имена для вложенных элементов. Парсер не поддерживает вложенность элементов с одинаковыми именами. Сообщения с разметкой поддерживают простые плейсхолдеры, но не полную грамматику ICU. Для работы с ней используйте вспомогательные функции текстовой грамматики. Поддерживаемые формы показаны в разделе Форматированный текст.
URL меняется, а язык — нет #
Обновляйте локаль и каталог вместе. Если изменить только локаль, французский текст может форматироваться по испанским правилам. Проверьте и вложенные провайдеры: дочерний провайдер с другой локалью работает независимо и не наследует каталог родительского.
Используйте механизм переключения выбранного адаптера. Next Pages использует навигацию через маршрутизатор и cookie локали. TanStack использует обычные ссылки, чтобы новый запрос мог загрузить новый каталог.
Текст, направление письма или даты меняются при гидратации #
Сравните входные данные на сервере и клиенте: версию каталога, локаль, значения, временную метку, часовой пояс и точку отсчёта относительного времени. Задайте lang и dir документа в оболочке фреймворка: базовый провайдер их не меняет. Затем проверьте исходный HTML и страницу после гидратации по контрольному списку серверного рендеринга.