Что такое локальные переводы?

Локальные переводы хранятся в бандле вашего приложения, а не загружаются из CDN (Content Delivery Network). Когда вы добавляете команду gtx-cli translate в процесс сборки, генерируются переводы в формате JSON. Заключительный шаг — поместить эти переводы в ваше приложение, чтобы они могли использоваться.

Есть два способа сделать это:

1. В бандле вашего приложения (локально): сохранить переводы в бандле после генерации
2. В CDN (по умолчанию): загружать переводы из CDN во время выполнения

По умолчанию gt-react загружает переводы из CDN General Translation. При переводе вашего приложения с использованием нашего API переводы автоматически сохраняются в нашем CDN.

Компромиссы и ограничения

Преимущества локальных переводов

• Более быстрая загрузка: Локальные переводы поставляются прямо из вашего приложения и загружаются быстрее, чем при получении с CDN
• Нет зависимости от внешних сервисов: Загрузка переводов в вашем приложении не зависит от доступности CDN. Если для локали переводы не найдены, приложение автоматически возвращается к языку по умолчанию
• Работает офлайн: Переводы входят в сборку вашего приложения

Недостатки локальных переводов

• Увеличение размера бандла: Локальные переводы увеличивают размер бандла приложения, что может замедлить его начальную загрузку
• Управление контентом: Чтобы отредактировать перевод, каждый раз нужно повторно разворачивать приложение с обновлённой версией перевода

Настройка

Шаг 1: Создайте функцию загрузки

Добавьте файл loadTranslations.[js|ts] в ./src со следующим содержимым:

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

Шаг 2: Настройте GTProvider

Передайте loadTranslations в качестве пропса компоненту <GTProvider>:

import { GTProvider } from 'gt-react';
import loadTranslations from './loadTranslations';

export default function App() {
  return (
    <GTProvider loadTranslations={loadTranslations} locales={['es', 'fr']}>
      <YourApp />
    </GTProvider>
  );
}

Шаг 3: Настройка CLI

Запустите команду настройки и выберите локальное хранилище:

npx gtx-cli configure

При появлении запроса:

• Сохранить в CDN? Выберите «No»
• Каталог переводов: CLI автоматически использует ./src/_gt

Также вы можете вручную настроить файл gt.config.json для использования локальных переводов. Подробнее см. в документации по конфигурации CLI.

Шаг 4: Сгенерируйте переводы

Теперь при запуске команды translate переводы будут автоматически загружаться и попадать в ваш кодовый репозиторий:

npx gtx-cli translate

Переводы будут храниться в src/_gt/ и поставляться вместе с вашим приложением.

Интеграция со сборочным процессом

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

Добавьте генерацию переводов в скрипт сборки:

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

Конвейер CI/CD

# .github/workflows/deploy.yml
- name: Сгенерировать переводы
  run: npx gtx-cli translate
  
- name: Сборка приложения  
  run: npm run build

Частые проблемы

Отсутствующие файлы переводов

Перед сборкой убедитесь, что переводы были сгенерированы:

# ❌ Сборка без переводов
<...YOUR_BUILD_COMMAND...>

# ✅ Сначала сгенерируйте переводы
npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>

Ошибки путей импорта

Отразите вашу структуру директорий в функции load:

// ❌ Неверный путь
const t = await import(`../translations/${locale}.json`);

// ✅ Правильный путь для src/_gt
const t = await import(`./_gt/${locale}.json`);

Большой размер бандла

Для приложений с множеством языков стоит рассмотреть код-сплиттинг:

// Загружайте переводы только при необходимости
export default async function loadTranslations(locale: string) {
  // Загружайте только если локаль активна
  if (locale === getCurrentLocale()) {
    const translations = await import(`./_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}

Дальнейшие шаги

• Руководство по языкам — настройка поддерживаемых языков