useLingo

useLingo() — так компоненты получают доступ к runtime. Хук находит ближайший <LingoProvider> и возвращает активный объект Lingo — вызывайте его один раз в компоненте, сохраняйте ссылку и используйте нужные методы.

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}

Если вызвать его вне provider, он выбросит исключение, поэтому в тестах нужно оборачивать render — даже в messages: {}, если переводы в этом тесте не важны.

`l.text(source, options)` — обычные строки#

Базовый вызов на каждый день. Возвращает переведённую строку, а если для текущей локали перевода нет — исходную.

tsx

l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)

Интерполяция#

Сегменты {placeholder} подставляются из options.values.

tsx

l.text("Welcome back, {name}!", {
  values: { name: user.firstName },
  context: "Dashboard greeting",
});

Если значений не хватает, {name} отрендерится буквально — удобно для поиска багов при разработке, но в тестах лучше проверять именно итоговый рендер, чтобы пустые значения не проскользнули незамеченными.

Когда в исходной строке есть синтаксис ICU#

Если исходная строка содержит маркеры plural / select / number / date, runtime автоматически переключится на нужный режим — без дополнительного API. Более удобную обёртку см. в Plurals and select.

`l.rich(source, options)` — поддеревья React#

Если в переведённом тексте есть React-компоненты (ссылки, полужирный текст, <Icon/>), используйте l.rich. Строка перевода содержит теги-заполнители вроде <link>...</link>, а вы сопоставляете каждому тегу свой рендерер.

tsx

l.rich("Click <link>here</link> for {topic}", {
  tags: {
    link: (children) => <a href="/help">{children}</a>,
  },
  values: { topic: "details" },
  context: "Footer help link",
});
// → <>Click <a href="/help">here</a> for details</>

Самозакрывающиеся теги тоже поддерживаются:

tsx

l.rich("Loading <spinner/>...", {
  tags: { spinner: () => <Spinner /> },
  context: "Inline loading state",
});

Теги без рендерера откатываются к исходному тексту — так отсутствие тега заметно в dev и не проглатывается молча.

Не вставляйте разметку прямо в переводимые строки. l.rich нужен, чтобы переводчики видели нейтральные заполнители (<link>) вместо <a href="...">, которые пришлось бы сохранять дословно и которые часто ломаются. Определяйте рендерер в коде, а не в файле локали.

Метаданные локали в `l`#

Помимо перевода, объект также предоставляет:

Свойство	Тип	Примечания
`l.locale`	`string`	Всё, что вы передали в `LingoProvider`. BCP-47.
`l.direction`	`"ltr"` \| `"rtl"`	Вычисляется через `Intl.Locale.textInfo` и резервный список RTL-языков.
`l.script`	`string` \| `undefined`	По возможности определяется автоматически (`"Latn"`, `"Cyrl"`, `"Arab"`, …).
`l.region`	`string` \| `undefined`	Определяется по BCP-47 (`"US"`, `"DE"`, `"SA"`, …).

Полезно для решений по компоновке:

tsx

const l = useLingo();
return <div dir={l.direction}>...</div>;

Методы форматирования#

В l также есть num, currency, percent, date, time, datetime, relative, list, displayName, sort, segment, fileSize, compact, unit — полный разбор см. в Formatting. Это тонкие обёртки над нативными форматтерами Intl.*, привязанными к l.locale.

Вне React#

useLingo работает только внутри компонентов. Для утилит, загрузчиков маршрутов или серверного кода создайте такой же объект напрямую:

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

const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });

Это объект той же формы, что и Lingo, и provider для него не нужен. Сам LingoProvider под капотом использует createLingo.

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}