# gt-react: General Translation React SDK: Словари
URL: https://generaltranslation.com/ru/docs/react/guides/dictionaries.mdx
---
title: Словари
description: Как использовать традиционные подходы к переводу на основе словарей
---

{/* СГЕНЕРИРОВАНО АВТОМАТИЧЕСКИ: не редактируйте напрямую. Вместо этого измените шаблон в content/docs-templates/. */}

Словари — это традиционный способ организации переводов в виде вложенных объектов с парами «ключ — значение». Хотя [`компоненты <T>`](/docs/react/guides/t) — рекомендуемый подход, словари могут быть полезны при миграции с других i18n-библиотек или если вы предпочитаете централизованно хранить переводы.

<Callout>
  **Рекомендация:** Для новых проектов используйте [`компоненты <T>`](/docs/react/guides/t). Словари поддерживаются главным образом для миграции и совместимости с существующими процессами перевода.
</Callout>


## Перевод через словарь vs перевод через компонент

### Паттерн со словарём

```tsx
// dictionary.ts
export default {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome, {name}!'
  }
};

// Использование компонента
function MyComponent() {
  const t = useTranslations();
  return <div>{t('greetings.hello')}</div>;
}
```


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

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


## Компромиссы

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

* **Централизованное хранение** - Все переводы собраны в одном месте
* **Привычный стандарт** - Знакомый подход из других библиотек i18n
* **Удобно для миграции** - Существующие переводы легко перенести

### Недостатки словаря

* **Сложность** - Требуется больше настроек и конфигурирования
* **Поддерживаемость** - Когда контент отделён от места использования, его сложнее обновлять
* **Удобство отладки** - Сложнее понять, к каким компонентам относятся переводы
* **Читаемость** - По ключам не видно реального содержимого

## Краткое руководство

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

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

```ts title="dictionary.ts"
const dictionary = {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome to our app!'
  },
  navigation: {
    home: 'Home',
    about: 'About',
    contact: 'Contact'
  }
};

export default dictionary;
```

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

```json title="dictionary.json"
{
  "greetings": {
    "hello": "Hello, world!",
    "welcome": "Welcome to our app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "About",
    "contact": "Contact"
  }
}
```

Затем передайте это компоненту [`<GTProvider>`](/docs/react/api/components/gtprovider):

```jsx title="index.js" copy
import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    {/* [!code highlight] */}
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);
```


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

Хук [`useTranslations`](/docs/react/api/dictionary/use-translations) предоставляет доступ к записям словаря:

```tsx
import { useTranslations } from 'gt-react';

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


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

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

```ts title="dictionary.ts"
const dictionary = {
  user: {
    greeting: 'Hello, {name}!',
    itemCount: 'You have {count} items',
    orderTotal: 'Total: ${amount}'
  }
};
```

```tsx
function UserDashboard() {
  const t = useTranslations();
  
  return (
    <div>
      <h1>{t('user.greeting', { name: 'Alice' })}</h1>
      <p>{t('user.itemCount', { count: 5 })}</p>
      <p>{t('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}
```

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

С помощью префиксов можно ограничить доступ к словарю конкретными разделами:

```ts title="dictionary.ts"
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Welcome back!',
      lastLogin: 'Last login: {date}'
    },
    stats: {
      totalUsers: 'Total Users: {count}',
      activeUsers: 'Active Users: {count}'
    }
  }
};
```

```tsx
function DashboardHeader() {
  // Префикс ограничивает доступ к 'dashboard.header'
  const t = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{t('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{t('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

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


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

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

Большинству пользователей стоит использовать [`loadTranslations`](/docs/react/api/config/load-translations), чтобы автоматически создавать переводы на основе базового словаря:

```ts title="dictionary.ts"  
const dictionary = {
  common: {
    save: 'Save',
    cancel: 'Cancel',
    delete: 'Delete'
  },
  forms: {
    required: 'This field is required',
    email: 'Please enter a valid email'
  }
};

export default dictionary;
```

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

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

Передайте это в `<GTProvider>`:

```tsx title="src/index.tsx"
import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider
      {...config}
      dictionary={dictionary}
      loadTranslations={loadTranslations}
    >
      <App />
    </GTProvider>
  </StrictMode>
);
```

GT автоматически генерирует переводы на другие языки на основе вашего базового словаря. Выполните `npx gt translate`, чтобы сгенерировать переводы для всех настроенных языков.


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

Для миграции с других библиотек i18n или при ручном управлении переводами используйте [`loadDictionary`](/docs/react/api/config/load-dictionary):

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

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

<Files>
  <Folder name="my-app" defaultOpen={true}>
    <Folder name="public" defaultOpen={true}>
      <Folder name="locales" defaultOpen={true}>
        <File name="es.json" />

        <File name="fr.json" />

        <File name="de.json" />
      </Folder>
    </Folder>

    <Folder name="src">
      <File name="loadDictionary.ts" />
    </Folder>
  </Folder>
</Files>

<Callout>
  **Выберите подходящий вариант:** Используйте [`loadTranslations`](/docs/react/api/config/load-translations) в новых проектах с автоматической генерацией переводов или [`loadDictionary`](/docs/react/api/config/load-dictionary) при переносе существующих файлов переводов.
</Callout>


## Продакшен-сетап

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

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

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <...YOUR_BUILD_COMMAND...>"
  }
}
```


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

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

## Использование вместе с компонентами

Словари и [компоненты `<T>`](/docs/react/guides/t) можно использовать вместе:

```tsx
function MixedApproach() {
  const t = useTranslations();
  
  return (
    <div>
      {/* Словарь для простых строк */}
      <h1>{t('page.title')}</h1>
      
      {/* Компонент T для сложного JSX */}
      <T>
        <p>This is a <strong>complex message</strong> with <a href="/link">links</a>.</p>
      </T>
      
      {/* Словарь для подписей полей формы */}
      <label>{t('forms.email')}</label>
    </div>
  );
}
```


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

<Callout>
  **Посмотрите в действии:** Ознакомьтесь с [примером приложения, демонстрирующим подход со словарём](https://github.com/gt-examples/dictionary-pattern), чтобы увидеть рабочее демо — [предпросмотр в реальном времени](https://dictionary-pattern.generaltranslation.dev).
</Callout>

* [Руководство по языкам](/docs/react/guides/languages) - Настройте поддерживаемые языки и параметры локали
* [Руководство по динамическому контенту](/docs/key-concepts/dynamic-content) - Решайте задачи перевода во время выполнения
* Справочник по API:
  * [Хук `useTranslations`](/docs/react/api/dictionary/use-translations)