Компонент Trans для JSX

Назначение и роль в экосистеме интернационализации

Компонент Trans является одним из ключевых механизмов интеграции интернационализации в React-приложениях при использовании i18next и его React-обвязки react-i18next. Он предназначен для рендеринга переводов, содержащих разметку JSX, вложенные компоненты и динамические значения, сохраняя при этом чистую структуру переводческих ресурсов.

Основная задача компонента — обеспечить безопасную и декларативную подстановку элементов интерфейса внутрь переводимых строк без необходимости ручного разбиения текста на фрагменты и без потери контекста перевода.

Базовая концепция работы Trans

Переводы в i18next традиционно представляют собой строки:

{
  "welcome": "Добро пожаловать, {{name}}"
}

Однако при наличии HTML-подобной структуры или React-компонентов строка становится недостаточной:

{
  "welcome": "Добро пожаловать, <strong>{{name}}</strong>"
}

Компонент Trans решает задачу интерпретации таких конструкций и их преобразования в React-дерево.

Синтаксис использования

Базовый пример

import { Trans } from "react-i18next";

function App() {
  return (
    <Trans i18nKey="welcome" values={{ name: "Alex" }} />
  );
}

Перевод:

{
  "welcome": "Добро пожаловать, {{name}}"
}

Вставка JSX-элементов в перевод

Одно из ключевых преимуществ Trans — возможность встраивания компонентов прямо в текст перевода.

Пример с выделением текста

<Trans i18nKey="description">
  Здесь находится <strong>важный текст</strong> внутри строки
</Trans>

Перевод:

{
  "description": "Здесь находится <1>важный текст</1> внутри строки"
}

Механика индексов

  • <0>, <1>, <2> — маркеры элементов
  • порядок соответствует порядку переданных компонентов

Передача компонентов через components prop

Рекомендуемый способ управления JSX-вставками:

<Trans
  i18nKey="description"
  components={{ bold: <strong />, link: <a href="/home" /> }}
/>

Перевод:

{
  "description": "Это <bold>жирный текст</bold> и <link>ссылка</link>"
}

Особенности:

  • ключи в components соответствуют именам тегов в переводе
  • позволяет избежать числовых индексов
  • повышает читаемость и поддерживаемость

Вложенные компоненты и сложная разметка

Trans поддерживает многослойные структуры:

<Trans
  i18nKey="complex"
  components={{
    bold: <strong />,
    italic: <em />,
    link: <a href="/docs" />
  }}
/>
{
  "complex": "Текст с <bold>жирным</bold>, <italic>курсивом</italic> и <link>ссылкой</link>"
}

Использование значений (values) внутри Trans

Интерполяция переменных

<Trans
  i18nKey="profile"
  values={{ username: "user_42", score: 1200 }}
/>
{
  "profile": "Пользователь {{username}} имеет {{score}} очков"
}

Совмещение с JSX

<Trans
  i18nKey="profile"
  values={{ username: "user_42" }}
  components={{ strong: <strong /> }}
/>
{
  "profile": "Пользователь <strong>{{username}}</strong>"
}

Вложенные HTML-подобные структуры

Trans интерпретирует псевдо-HTML внутри переводов.

Пример с вложенными тегами

{
  "nested": "Текст <0>с <1>вложенным</1> элементом</0>"
}
<Trans
  i18nKey="nested"
  components={[<span />, <strong />]}
/>

Работа с контекстом и семантической структурой

Trans сохраняет структуру перевода, не разрушая семантику строки:

  • перевод хранится централизованно
  • структура UI определяется компонентами
  • логика разметки отделена от текста

Это позволяет избегать:

  • разбиения строк на части в коде
  • дублирования UI-логики в переводах
  • потери контекста при локализации

Обработка вложенных переменных и JSX одновременно

<Trans
  i18nKey="order"
  values={{ id: 15 }}
  components={{ bold: <strong /> }}
/>
{
  "order": "Заказ <bold>#{{id}}</bold> успешно создан"
}

Особенности экранирования

В переводах важно учитывать специальные символы:

  • < > используются как маркеры компонентов
  • двойные фигурные скобки {{ }} используются для переменных

Неправильное использование приводит к:

  • некорректному парсингу
  • потере части строки
  • нарушению структуры React-дерева

Условная структура и ограничения Trans

Компонент Trans не является шаблонизатором общего назначения. Ограничения:

  • отсутствует произвольная логика внутри переводов
  • невозможны выражения или вычисления
  • не поддерживаются циклы
  • структура должна быть заранее определена

Использование with i18next namespaces

При работе с пространствами имён:

<Trans i18nKey="header:title" />

или

<Trans ns="header" i18nKey="title" />

Структура переводов:

{
  "header": {
    "title": "Заголовок страницы"
  }
}

Интеграция с React-рендерингом

Trans возвращает React-элементы, что позволяет:

  • использовать внутри JSX-дерева без обёрток
  • комбинировать с другими компонентами
  • встраивать в условный рендеринг
{isVisible && <Trans i18nKey="message" />}

Производительность и поведение при рендере

При каждом рендере:

  • выполняется разрешение ключа перевода
  • происходит построение React-дерева
  • применяется интерполяция значений

Оптимизация достигается через:

  • мемоизацию переводов внутри i18next
  • стабильные ключи i18nKey
  • минимизацию динамических изменений компонентов

Частые ошибки при использовании Trans

Несовпадение структуры перевода и компонентов

{ "text": "Hello <bold>world</bold>" }
<Trans i18nKey="text" components={{ strong: <strong /> }} />

Несовпадение bold и strong приводит к отсутствию форматирования.

Избыточная вложенность

Чрезмерное количество уровней <0><1><2> усложняет поддержку и снижает читаемость переводов.

Перенос логики в переводы

Переводы не предназначены для бизнес-логики или вычислений, их задача — исключительно представление текста.

Сравнение Trans и useTranslation

  • useTranslation — получение строки перевода
  • Trans — рендеринг JSX-структуры внутри перевода
const { t } = useTranslation();
t("key");
<Trans i18nKey="key" />

Trans применяется при наличии:

  • HTML-подобной разметки
  • React-компонентов внутри текста
  • сложной структуры отображения

Управление вложенными компонентами через массив

<Trans
  i18nKey="example"
  components={[<span />, <strong />, <a href="/" />]}
/>

Перевод:

{
  "example": "<0>Текст</0> и <1>выделение</1> и <2>ссылка</2>"
}

Поведение при отсутствии ключа перевода

Если ключ отсутствует:

  • возвращается fallback-строка
  • или сам children внутри Trans
  • или пустой результат, в зависимости от конфигурации i18next

Использование Trans в крупных приложениях

В архитектурах с высокой степенью локализации Trans становится центральным элементом UI-слоя:

  • обеспечивает единый формат перевода
  • позволяет локализовать сложные интерфейсы
  • минимизирует дублирование UI-структур
  • отделяет текст от логики компонентов
Оглавление