Обзор

gt-react теперь экспортирует функцию t() для синхронного перевода строк на уровне модуля в браузере.

До сих пор для перевода строк в gt-react требовались хуки на основе контекста React, такие как useGT. Хуки хорошо работают внутри компонентов, но не покрывают распространённый сценарий: перевод строк на уровне модуля — вне компонентов React, до рендеринга, в обычных вспомогательных файлах.

t() решает эту проблему. Это синхронная функция, которую можно вызывать где угодно в браузерном коде:

import { t } from 'gt-react/browser';

const greeting = t('Hello, world!');

Не нужны ни хуки, ни async, ни дерево компонентов.

Почему именно такой подход

Основная идея этого PR — попробовать уйти от подхода к переводу через контекст React. Поскольку t() работает вне дерева компонентов, он открывает более интересные сценарии — в первую очередь перевод на уровне модуля. Строки можно переводить там, где они объявлены, а не там, где они рендерятся.

У этого есть свои компромиссы:

• Только на стороне клиента. t() работает только в клиентских React-приложениях. Он опирается на выполнение модулей в браузере, чтобы загрузить переводы до рендеринга приложения.
• Для смены языка нужна полная перезагрузка страницы. Поскольку переводы вычисляются при загрузке модуля, смена локали требует повторного выполнения модулей — то есть полной перезагрузки страницы. Горячее переключение языков посреди сессии не поддерживается.

С другой стороны, удобство для разработчика заметно улучшается. Не нужно оборачивать строки в хуки, не нужна обвязка на уровне компонентов, нет асинхронных границ — только вызов функции.

Существующие подходы через React context (useGT, <T> и т. д.) никуда не исчезают. Это дополнительный вариант для проектов, где такие компромиссы оправданы.

Как это работает

t() синхронно получает переводы из заранее загруженных данных. Эти переводы подготавливаются функцией bootstrap() — новой асинхронной функцией инициализации, которая загружает все переводы для текущей локали до рендеринга приложения.

Вам нужно изменить точку входа приложения так, чтобы сначала выполнялась bootstrap(). Обычно это main.tsx, но при необходимости точку входа можно изменить в index.html.

// bootstrap.tsx (новая точка входа)
import gtConfig from '../gt.config.json';
import { bootstrap } from 'gt-react/browser';

async function getTranslations(locale: string) {
  return import(`./_gt/${locale}.json`);
}

await bootstrap({
  ...gtConfig,
  getTranslations,
});

await import('./main.tsx');

Функция getTranslations асинхронная: сначала она загружает переводы, а затем импортируется и запускается React-приложение. Именно поэтому t() доступна на уровне модуля: к моменту, когда любой модуль вызывает t(), переводы уже загружены.

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

Переменные

t() поддерживает подстановку переменных, как и msg():

import { t } from 'gt-react/browser';

t('Hello, {name}!', { name: 'John' });  // → "Hola, John!"

Где это применимо

t() — правильный выбор, когда переводы нужны вне дерева компонентов React: в файлах констант, вспомогательных функциях, объектах конфигурации, определениях роутов или в любом коде, который выполняется на уровне модуля в браузере.

Имейте в виду:

• Пока это не интегрировано с остальной системой gt-react. Вам нужно выполнить начальную настройку, описанную выше. Это отдельный подход.
• Только на стороне клиента. Для перевода на стороне сервера следует использовать хуки на основе контекста React, например useGT.

Примечания по реализации

t() работает только в браузере. Если вызвать её на сервере (где window не определён), будет выведено предупреждение, а функция вернёт исходную строку. Это сделано намеренно — для перевода на стороне сервера следует использовать существующие хуки React, основанные на контексте.

Справочник по API

См. полный справочник по API t(), где приведены параметры, типы возвращаемых значений и сведения о настройке.