Провайдер и хуки

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

LingoProvider предоставляет поддереву компонентов одну локаль и каталог. useLingo() обращается к ближайшему провайдеру и возвращает методы для работы с сообщениями и форматирования с учётом этих данных.

Для этих примеров рендеринга нужен React 19. Прежде чем использовать провайдер, выполните инструкции по установке из краткого руководства по React.

tsx
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 в компоненте внутри провайдера. Вызов вне провайдера приводит к исключению. Если компонент возвращает провайдер, хук этого компонента всё равно остаётся вне него. Поэтому вынесите обёртку с провайдером отдельно от компонента, который использует хук.

Как объединять общие сообщения и сообщения страницы #

Вложенные провайдеры с одинаковой строкой локали объединяют свои словари. Записи дочернего провайдера заменяют родительские записи с теми же ключами. Остальные записи родительского провайдера остаются доступными. Так маршрут может добавлять сообщения страницы, не дублируя общие сообщения навигации.

tsx
<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:

ts
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. Используйте метаданные локали, чтобы задать атрибуты документа, и сохраняйте те же входные данные при гидратации.