Провайдер и хуки
Передавайте локаль и каталог, объединяйте общие сообщения и сообщения страницы, переключайте языки, не смешивая данные для рендеринга.
LingoProvider предоставляет поддереву компонентов одну локаль и каталог. useLingo() обращается к ближайшему провайдеру и возвращает методы для работы с сообщениями и форматирования с учётом этих данных.
Для этих примеров рендеринга нужен React 19. Прежде чем использовать провайдер, выполните инструкции по установке из краткого руководства по React.
import { LingoProvider, useLingo, type Messages } from "@lingo.dev/react";
function SaveButton() {
const l = useLingo();
return (
<button type="submit">
{l.text("Save", { context: "Submit changes to account settings" })}
</button>
);
}
export function Settings({ messages }: { messages: Messages }) {
return (
<LingoProvider locale="fr" messages={messages}>
<SaveButton />
</LingoProvider>
);
}Загрузите сообщения на французском до рендеринга Settings. Провайдер принимает Messages типа Record<string, string>, а не путь к файлу, промис или список записей после разбора JSONC. Такой словарь получается при загрузке каталога.
Входные данные провайдера #
| Свойство | Требования |
|---|---|
locale | Обязательная строка для диагностики поиска сообщений, применения грамматических правил и форматирования. |
messages | Необязательный словарь строк с хешами в качестве ключей. По умолчанию — {}. |
children | Обязательное поддерево ReactNode. |
Даже с пустым каталогом поддереву доступно форматирование с учётом локали. При вызове сообщений используются исходные шаблоны. Сам провайдер не задаёт язык документа или направление текста.
Вызывайте useLingo в компоненте внутри провайдера. Вызов вне провайдера приводит к исключению. Если компонент возвращает провайдер, хук этого компонента всё равно остаётся вне него. Поэтому вынесите обёртку с провайдером отдельно от компонента, который использует хук.
Как объединять общие сообщения и сообщения страницы #
Вложенные провайдеры с одинаковой строкой локали объединяют свои словари. Записи дочернего провайдера заменяют родительские записи с теми же ключами. Остальные записи родительского провайдера остаются доступными. Так маршрут может добавлять сообщения страницы, не дублируя общие сообщения навигации.
<LingoProvider locale="fr" messages={sharedMessages}>
<LingoProvider locale="fr" messages={pageMessages}>
<SettingsPage />
</LingoProvider>
</LingoProvider>Здесь sharedMessages и pageMessages — уже загруженные словари на французском. Если локаль внутреннего провайдера меняется на es, он становится независимым: вместо недостающих испанских сообщений используются исходные шаблоны, а не французский текст. Строки локали сравниваются буквально, поэтому придерживайтесь одного написания локали во всём приложении.
Как переключать локаль и каталог вместе #
Храните данные для рендеринга в паре, например { locale: "fr", messages: frenchMessages }. Загрузите следующий словарь, затем замените пару одним обновлением состояния. Если изменить только локаль, на экране может остаться французский текст с числами в испанском формате.
Пока загружается следующий каталог, оставляйте на экране результат рендеринга с предыдущей парой или показывайте состояние загрузки — в зависимости от того, как устроено взаимодействие в приложении. В приложениях с маршрутизацией используйте соответствующий пример для Next Pages или TanStack: их переключатели по-разному загружают новые данные.
Как создать объект Lingo без хука #
Используйте createLingo(locale: string, messages?: Messages): Lingo, когда функции нужна строка вне компонента React:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });Этот вызов возвращает Account settings и форматирует отношение как 12.5% с учётом этой локали. Он не отправляет запрос на перевод и не подписывается на провайдер. При изменении локали или сообщений создавайте новый объект.
И createLingo, и useLingo предоставляют locale, direction, script и region. Используйте метаданные локали, чтобы задать атрибуты документа, и сохраняйте те же входные данные при гидратации.