Сообщения с форматированием

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

Ссылка часто бывает частью предложения. Если переводить текст до ссылки, внутри неё и после неё по отдельности, придётся сохранять порядок слов исходного языка. l.rich позволяет переводить предложение целиком, а переведённому шаблону — размещать именованные элементы React там, где нужно.

Не разбивайте предложение #

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

export function PurchaseNotice({ product }: { product: string }) {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <link>refund policy</link> before buying {product}.", {
        context: "Purchase notice linking to the refund policy",
        values: { product },
        tags: {
          link: (children) => <a href="/refund-policy">{children}</a>,
        },
      })}
    </p>
  );
}

Разместите этот компонент внутри провайдера. Исходный текст и контекст определяют запись в каталоге так же, как для l.text. Переведённый шаблон задаёт текст и расположение тегов, а функция обратного вызова — адрес ссылки, атрибуты, стили и поведение.

l.rich возвращает ReactNode. Его RichOptions требует context, принимает карту values со строковыми или числовыми значениями, а также tags: Record<string, (children: ReactNode) => ReactNode>. Имена тегов должны совпадать в точности, поэтому для <link> нужна функция обратного вызова link.

Как вставить элемент без дочерних элементов #

Самозакрывающийся тег вызывает свою функцию рендеринга, передавая null в качестве дочерних элементов. Например, в этом подтверждении после сообщения появляется декоративный значок:

tsx
const confirmation = l.rich("Saved <icon/>", {
  context: "Confirmation that account settings were saved",
  tags: {
    icon: () => <span aria-hidden="true">✓</span>,
  },
});

Здесь l — результат useLingo() компонента. Поддерживаются и <icon/>, и <icon />. Для вложенных элементов используйте разные имена, например <link><strong>refund policy</strong></link>, и передайте обе функции обратного вызова. Парсер использует следующий закрывающий тег с совпадающим именем. Вложенные теги с одинаковыми именами не обрабатываются как сбалансированная HTML-структура.

Проверяйте в переводе не только слова, но и теги #

Если для парного или самозакрывающегося тега нет функции обратного вызова, он остаётся обычным текстом. Открывающий тег без соответствующего закрывающего тоже остаётся текстом. Сообщение по-прежнему можно показать, но вместо рабочей ссылки читатель может увидеть <link>.

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

Поддерживаемая разметка — это именованные теги, а не произвольный HTML. Задавайте атрибуты в функции обратного вызова, а не в переводе. Использование dangerouslySetInnerHTML для обработки тега без пары нарушит это разделение.

Используйте простые значения в сообщениях с форматированием #

В текстовых фрагментах сообщений с форматированием подставляются простые значения {name}. Сложный форматировщик ICU, который используется в l.text, здесь не запускается. Для грамматических форм, зависящих от количества, используйте множественные формы и выбор вариантов. Другой вариант — строить интерфейс на основе грамматически завершённых сообщений, которые можно выразить в поддерживаемом формате. Выражение ICU для множественных форм внутри шаблона с форматированием не начнёт выбирать нужную форму лишь потому, что в нём есть фигурные скобки.