Локализуйте интерактивные сообщения с разметкой
Переводите предложение целиком, оставляя управление ссылками, компонентами и значениями в коде React.
«Прочитайте правила, прежде чем продолжить» — одно предложение, даже если «правила» — ссылка. Перевод целого предложения позволяет переместить ссылку туда, где она нужна в другом языке, а управление её адресом оставить в коде приложения.
Метод rich из пакета React представляет эту ссылку как именованный слот. Каталог задаёт предложение, а функция рендеринга React — компонент для этого слота.
Выведите предложение со ссылкой целиком #
Установите @lingo.dev/react в существующее приложение на React 19. Этот локальный пример использует демонстрационный каталог на испанском и не требует отправлять запрос на перевод:
npm install @lingo.dev/reactimport { 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-атрибуты.
Для меняющихся значений используйте именованные плейсхолдеры:
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 и выполните:
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.