Консоль

Словари

Как использовать традиционные шаблоны перевода на базе словарей

Словари — это традиционный способ организовывать переводы во вложенных объектах с парами «ключ — значение». Хотя рекомендуемым подходом являются компоненты <T>, словари могут быть полезны при миграции с других i18n‑библиотек или если вы предпочитаете централизованное хранение переводов.

Рекомендация: используйте компоненты <T> для новых проектов. Поддержка словарей предусмотрена в первую очередь для миграции и совместимости с существующими процессами перевода.

Словарь vs перевод компонентов

Шаблон «словарь»

// dictionary.ts
export default {
  greetings: {
    hello: 'Привет, мир!',
    welcome: 'Добро пожаловать, {name}!'
  }
};

// Component usage
function MyComponent() {
  const d = useTranslations();
  return <div>{d('greetings.hello')}</div>;
}

Паттерн компонента

// Прямое использование компонента — рекомендуется
function MyComponent() {
  return <T><div>Привет, мир!</div></T>;
}

Компромиссы

Преимущества словаря

  • Централизованное хранение — все переводы в одном месте
  • Отраслевой стандарт — привычный подход из других библиотек i18n
  • Удобная миграция — легко перенести существующие переводы

Недостатки подхода с словарём

  • Сложность — требуется больше настрой и конфигурации
  • Сопровождаемость — отделение контента от места использования усложняет обновления
  • Отлаживаемость — сложнее связать перевод с конкретными компонентами
  • Читаемость — по ключам не видно реального содержимого

Быстрый старт

Шаг 1: Создайте словарь

Создайте файл словаря в корне проекта или в каталоге src:

dictionary.ts
const dictionary = {
  greetings: {
    hello: 'Привет, мир!',
    welcome: 'Добро пожаловать в наше приложение!'
  },
  navigation: {
    home: 'Главная',
    about: 'О компании',
    contact: 'Связаться с нами'
  }
};

export default dictionary;

Или используйте формат JSON:

dictionary.json
{
  "greetings": {
    "hello": "Привет, мир!",
    "welcome": "Добро пожаловать в наше приложение!"
  },
  "navigation": {
    "home": "Главная", 
    "about": "О нас",
    "contact": "Контакты"
  }
}

Функция withGTConfig автоматически обнаружит файл словаря в корне проекта или в каталоге src.

Шаг 2: Использование в компонентах

Хук useTranslations позволяет обращаться к записям словаря:

Компоненты клиента

import { useTranslations } from 'gt-next';

function MyComponent() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Серверные компоненты

import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{d('greetings.hello')}</h1>
      <p>{d('greetings.welcome')}</p>
    </div>
  );
}

Использование переменных

Добавляйте переменные в записи словаря с помощью синтаксиса {variable}:

dictionary.ts
const dictionary = {
  user: {
    greeting: 'Здравствуйте, {name}!',
    itemCount: 'У вас {count} предметов',
    orderTotal: 'Итого: ${amount}'
  }
};
function UserDashboard() {
  const d = useTranslations();
  
  return (
    <div>
      <h1>{d('user.greeting', { name: 'Alice' })}</h1>
      <p>{d('user.itemCount', { count: 5 })}</p>
      <p>{d('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}

Использование префиксов

Ограничивайте доступ к словарю для определённых разделов с помощью префиксов:

dictionary.ts
const dictionary = {
  dashboard: {
    header: {
      welcome: 'С возвращением!',
      lastLogin: 'Последний вход: {date}'
    },
    stats: {
      totalUsers: 'Всего пользователей: {count}',
      activeUsers: 'Активных пользователей: {count}'
    }
  }
};
function DashboardHeader() {
  // Префикс ограничивает доступ к 'dashboard.header'
  const d = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{d('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{d('lastLogin', { date: 'Сегодня' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Другой префикс для раздела статистики
  const d = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{d('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{d('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}

Поддержка нескольких языков

Автоматический перевод (рекомендуется)

Большинству пользователей следует использовать loadTranslations, чтобы автоматически генерировать переводы из вашей базовой словарной базы:

dictionary.ts
const dictionary = {
  common: {
    save: 'Сохранить',
    cancel: 'Отменить',
    delete: 'Удалить'
  },
  forms: {
    required: 'Обязательное поле',
    email: 'Введите корректный адрес электронной почты'
  }
};

export default dictionary;

Создайте функцию loadTranslations для загрузки сгенерированных файлов переводов:

src/loadTranslations.ts
export default async function loadTranslations(locale) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

withGTConfig автоматически подхватывает файл loadTranslations.[js|ts] из каталога src/ или из корня проекта.

GT автоматически генерирует переводы на другие языки на основе вашей базовой словарной базы. Запустите npx gtx-cli translate, чтобы сгенерировать переводы для всех настроенных языков.

Файлы ручных переводов (миграция)

Для миграции с других библиотек i18n или при ручном управлении переводами используйте loadDictionary:

src/loadDictionary.ts
export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}

Это загружает JSON‑файлы переводов из каталога public/locales/:

es.json
fr.json
de.json

Выберите подходящий вариант: используйте loadTranslations для новых проектов с автоматической генерацией переводов или loadDictionary при миграции существующих файлов переводов.

Настройка продакшн-среды

Процесс сборки

Добавьте переводы в ваш конвейер сборки:

package.json
{
  "scripts": {
    "build": "npx gtx-cli translate && <...ВАША_КОМАНДА_СБОРКИ...>"
  }
}

Поведение в разработке и продакшене

  • Разработка: Записи словаря переводятся по запросу с использованием dev API key
  • Продакшен: Все переводы словаря предварительно формируются на этапе сборки

Совмещение с компонентами

Словари и компоненты <T> могут работать вместе:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Словарь для простых строк */}
      <h1>{d('page.title')}</h1>
      
      {/* Компонент T для сложного JSX */}
      <T>
        <p>Это <strong>сложное сообщение</strong> со <a href="/link">ссылками</a>.</p>
      </T>
      
      {/* Словарь для меток форм */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Следующие шаги

Насколько полезно это руководство?

На этой странице

Словарь vs перевод компонентов
Шаблон «словарь»
Паттерн компонента
Компромиссы
Преимущества словаря
Недостатки подхода с словарём
Быстрый старт
Шаг 1: Создайте словарь
Шаг 2: Использование в компонентах
Компоненты клиента
Серверные компоненты
Использование переменных
Использование префиксов
Поддержка нескольких языков
Автоматический перевод (рекомендуется)
Файлы ручных переводов (миграция)
Настройка продакшн-среды
Процесс сборки
Поведение в разработке и продакшене
Совмещение с компонентами
Следующие шаги
Словари