Локализуйте интерактивные сообщения с разметкой

Переводите предложение целиком, оставляя управление ссылками, компонентами и значениями в коде React.

«Прочитайте правила, прежде чем продолжить» — одно предложение, даже если «правила» — ссылка. Перевод целого предложения позволяет переместить ссылку туда, где она нужна в другом языке, а управление её адресом оставить в коде приложения.

Метод rich из пакета React представляет эту ссылку как именованный слот. Каталог задаёт предложение, а функция рендеринга React — компонент для этого слота.

Выведите предложение со ссылкой целиком #

Установите @lingo.dev/react в существующее приложение на React 19. Этот локальный пример использует демонстрационный каталог на испанском и не требует отправлять запрос на перевод:

sh
npm install @lingo.dev/react
tsx
import { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";

const messages = {
  [computeKey(
    "Read the <policy>policy</policy> before continuing.",
    "Notice before account creation",
  )]: "Antes de continuar, lee la <policy>política</policy>.",
};

function ConsentNotice() {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <policy>policy</policy> before continuing.", {
        context: "Notice before account creation",
        tags: {
          policy: (children) => <a href="/policy">{children}</a>,
        },
      })}
    </p>
  );
}

export function App() {
  return (
    <LingoProvider locale="es" messages={messages}>
      <ConsentNotice />
    </LingoProvider>
  );
}

В абзаце должен появиться текст «Antes de continuar, lee la política.» В переводе упоминание правил меняет место, но ссылка по-прежнему ведёт на /policy. Исходный текст, заданный строковым литералом, и контекст в вызове также позволяют распознать сообщение при извлечении. computeKey формирует настоящий идентификатор тестовых данных, не полагаясь на выдуманный хеш.

Сейчас провайдер использует синтаксис контекста React 19, хотя в peer-зависимостях пакета указаны React 18 и 19. Работу с React 18 проверьте отдельно. В кратком руководстве по React описаны настройка провайдера и создание первого каталога.

Оставьте значения и поведение в коде #

Имя policy обозначает слот, а не HTML-элемент, заданный переводчиком. Функция рендеринга слота управляет адресом ссылки и её поведением. Определяйте адрес для конкретной локали по заранее заданной в коде таблице маршрутов. Не включайте в каталог обработчики событий и произвольные HTML-атрибуты.

Для меняющихся значений используйте именованные плейсхолдеры:

tsx
const greeting = l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

const countLabel = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the cart" },
);

const roleLabel = l.select(
  role,
  { admin: "Administrator", other: "Member" },
  { context: "Account role label" },
);

Разместите эти вызовы внутри компонента с const l = useLingo() и значениями приложения для name, count и role. text возвращает обычный текст, plural выбирает грамматическую форму в зависимости от количества, а select ищет точное совпадение селектора и использует other как запасной вариант. Обработка текста с разметкой поддерживает именованные теги и простую подстановку значений, но не запускает форматировщик сложных выражений ICU, доступный для обычного текста. Для такого выбора во время выполнения используйте множественные формы, даты и числа.

Исходный текст должен быть статичным. Если включить в исходную строку имя человека, для каждого человека получится свой текст, что помешает надёжному извлечению. Контекст должен объяснять назначение сообщения, например «Метка роли учётной записи», потому что исходный текст и контекст вместе определяют идентификатор. Если переводы уже есть, меняйте контекст обдуманно.

Замените локальные тестовые данные извлечёнными каталогами #

Установите актуальную версию CLI и выполните:

sh
lingo extract --src src --source-locale en

Если не переопределять пути, команда запишет locales/en.jsonc и lingo.d.ts. Проверьте извлечённый исходный текст, контекст и ключ. Включите файл объявлений в конфигурацию TypeScript приложения. Извлечение поддерживает распознаваемые вызовы сообщений, но не обнаруживает произвольные исходные строки, созданные динамически.

Следуйте краткому руководству по CLI, чтобы пройти аутентификацию и привязать движок локализации. Затем выберите в .lingo/config.json именно этот источник locales/en.jsonc и нужные целевые локали. Переведите и получите каталог с помощью этого файлового рабочего процесса. Следуйте инструкции по загрузке каталога, чтобы разобрать JSONC, выбрать активные ключи из соответствующей ревизии исходного каталога и передать строки перевода провайдеру. Универсальный переводчик файлов не сохраняет комментарии исходного каталога в переведённом файле.

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

Проверьте взаимодействие и обработку некорректных сообщений #

Перейдите по ссылке на правила с помощью клавиатуры и проверьте её доступное имя. После перемещения ссылки прочитайте текст вокруг неё, обращая внимание на пунктуацию. Полноценный перевод должен сохранять и смысл предложения, и действие, доступное читателю.

В локальном тестовом каталоге удалите обработчик тега, добавьте неизвестный тег и оставьте тег незакрытым. Сейчас функция рендеринга оставляет неизвестную или непарную разметку в виде текста. Сопоставление пар вложенных одноимённых тегов работает с ограничениями. Это не универсальная функция рендеринга HTML и не валидатор, который отклоняет любое некорректное сообщение.

Для обычного текста проверьте случаи с отсутствующими значениями и некорректными сложными сообщениями ICU: плейсхолдеры без подставленных значений или неотформатированный шаблон могут остаться на экране, а в режиме разработки появятся диагностические сообщения. Для сообщений с количеством и ролью проверьте категории множественного числа целевого языка и неизвестную роль. Точное поведение в этих случаях описано в справочнике по тексту с разметкой и рекомендациях по тестированию React.