# gt-react: General Translation React SDK: t URL: https://generaltranslation.com/ru/docs/react/api/strings/t-function.mdx --- title: t description: Справочник по API синхронной функции перевода строк `t()` --- ## Обзор Функция `t` — это синхронная функция перевода строк на уровне модуля для React-приложений, работающих на стороне клиента. ```jsx import { t } from 'gt-react/browser'; const greeting = t('Hello, world!'); ``` `t` также можно использовать в виде тегированного шаблонного литерала: ```jsx import { t } from 'gt-react/browser'; const greeting = t`Hello, ${name}!`; ``` В отличие от `useGT` (который требует контекста React) и `msg` (который кодирует строки для последующей обработки), `t()` сразу возвращает переведённую строку. `t()` можно вызывать где угодно в браузерном коде — в том числе на уровне модуля, вне компонентов React. **Экспериментально:** `t()` — экспериментальная возможность. Она предназначена только для React-приложений, работающих только на стороне клиента, и пока не интегрируется с контекстом React (например, ``, `useGT`). Если вызвать её на сервере, она выводит предупреждение в лог и возвращает исходную строку. *** ## Сетап `t()` зависит от `bootstrap()`: он загружает переводы до рендеринга приложения. Вам нужно изменить точку входа приложения так, чтобы сначала запускался `bootstrap()`. Обычно точка входа — `main.tsx`. Создайте новый файл (например, `bootstrap.tsx`) и укажите его в `index.html` вместо текущего. ### 1. Создайте точку входа для bootstrap ```tsx // bootstrap.tsx import gtConfig from '../gt.config.json'; import { bootstrap } from 'gt-react/browser'; async function loadTranslations(locale: string) { return (await import(`./_gt/${locale}.json`)).default; } await bootstrap({ ...gtConfig, loadTranslations, }); await import('./main.tsx'); ``` По умолчанию `bootstrap()` автоматически обновляет атрибуты `lang` и `dir` элемента `` в соответствии с текущей локалью. Это поведение можно настроить с помощью `htmlTagOptions`: ```tsx await bootstrap({ ...gtConfig, loadTranslations, htmlTagOptions: { updateHtmlLangTag: true, // по умолчанию: true updateHtmlDirTag: false, // по умолчанию: true }, }); ``` Вы также можете в любой момент вручную изменить эти атрибуты с помощью вспомогательных функций `updateHtmlTagLang` и `updateHtmlTagDir` из `gt-react/browser`. ### 2. Обновите `index.html` В файле `index.html` обновите точку входа модуля: она должна указывать на новый bootstrap-файл вместо `main.tsx`: ``` src="/src/bootstrap.tsx" ``` ### 3. Используйте `t()` где угодно ```tsx import { t } from 'gt-react/browser'; // Уровень модуля — выполняется при импорте const navItems = [ { label: t('Home'), path: '/' }, { label: t('About'), path: '/about' }, { label: t('Contact'), path: '/contact' }, ]; export default function Nav() { return ( ); } ``` **Автономный setup:** `t()` в настоящее время не интегрируется с остальной системой `gt-react` (например, ``, `useGT`). Необходимо использовать bootstrap setup, описанный выше. *** ## Тегированный шаблонный литерал `t` можно использовать как тегированный шаблонный литерал с более естественным синтаксисом: ```tsx import { t } from 'gt-react/browser'; // Оба варианта эквивалентны: t('Hello, {name}!', { name: 'Alice' }); t`Hello, ${name}!`; ``` Форма с тегированным шаблонным литералом избавляет от необходимости использовать заполнители в стиле ICU и объекты параметров — переменные подставляются напрямую из выражения шаблона. ### Глобальная регистрация Вместо того чтобы импортировать `t` в каждом файле, его можно зарегистрировать глобально: ```tsx // В точке входа вашего приложения import "gt-react/macros"; ``` Это устанавливает `globalThis.t`, поэтому тегированный шаблонный литерал доступен везде без явного импорта: ```tsx // Импорт не нужен const labels = { save: t`Save`, cancel: t`Cancel`, }; ``` *** ## Справочник ### Параметры | Имя | Тип | Описание | | ---------- | -------- | --------------------------------------------------------------------------------- | | `message` | `string` | Строка для перевода. | | `options?` | `object` | Необязательный параметр. Объект, содержащий значения переменных для интерполяции. | ### Возвращает `string` — Переведённая строка для текущей локали или исходная строка, если перевод отсутствует. *** ## Переменные Вы можете передавать переменные с помощью синтаксиса фигурных скобок: ```tsx import { t } from 'gt-react/browser'; const message = t('Hello, {name}!', { name: 'Alice' }); // → "Hola, Alice!" (на испанском) ``` Или используйте тегированный шаблонный литерал — он автоматически обрабатывает интерполяцию: ```tsx import { t } from 'gt-react/browser'; const message = t`Hello, ${name}!`; // → "Hola, Alice!" (на испанском, при name = 'Alice') ``` Значения переменных не переводятся — переводится только окружающий шаблон строки. *** ## Поведение ### Как это работает `bootstrap()` асинхронно загружает все переводы для текущей локали до импорта модулей приложения. После этого `t()` синхронно обращается к данным переводов без дополнительных накладных расходов. Поскольку переводы определяются во время загрузки модулей: * **Переключение локали требует полной перезагрузки страницы.** Браузер должен заново выполнить все модули, чтобы подхватить новые переводы. * **Это работает только в приложениях на стороне клиента.** Код на уровне модуля заново выполняется при загрузке в браузере, и именно это делает такой подход возможным. ### Поведение на сервере Если `t()` вызывается в серверной среде (где `window` не определён), он выводит предупреждение в лог и возвращает исходную строку. Для перевода на стороне сервера используйте хуки на основе контекста React, например `useGT`. *** ## Пример ### Файл с константами ```tsx // constants.ts import { t } from 'gt-react/browser'; export const ERROR_MESSAGES = { notFound: t('Page not found'), unauthorized: t('You do not have permission to view this page'), serverError: t('Something went wrong. Please try again later.'), }; ``` ### Определения роутера ```tsx // routes.ts import { t } from 'gt-react/browser'; export const routes = [ { path: '/', label: t('Home') }, { path: '/dashboard', label: t('Dashboard') }, { path: '/settings', label: t('Settings') }, ]; ``` *** ## Примечания * `t()` импортируется из `gt-react/browser`, а не напрямую из `gt-react`. * `bootstrap()` нужно вызвать до загрузки любого модуля, использующего `t()`. * **Экспериментально.** Пока не интегрируется с `` и другими возможностями `gt-react`, основанными на контексте. * Переключение локали требует полной перезагрузки страницы. ## Дневники разработки * [gt-react@10.12.0](/devlog/gt-react_v10_12_0) — добавлена функция `t()` * [gt-react@10.13.0](/devlog/gt-react_v10_13_0) — поддержка тегированных шаблонных литералов ## Что дальше * См. [`useGT`](/docs/react/api/strings/use-gt), чтобы переводить строки внутри компонентов React. * См. [`msg`](/docs/react/api/strings/msg), чтобы кодировать строки для последующего перевода.