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

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

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

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

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

Баланс выгод и затрат

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

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

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

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

Установка

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

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

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

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

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

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

npx gtx-cli configure

Когда будет предложено:

• Сохранить в CDN? Выберите «Нет»
• Каталог переводов: Введите ./public/_gt

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

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

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

npx gtx-cli translate

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

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

Процесс сборки Next.js

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

{
  "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`);

// ✅ Корректный путь для public/_gt
const t = await import(`../public/_gt/${locale}.json`);

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

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

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

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

• Руководство по middleware — обнаружение языка и маршрутизация
• Руководство по языкам — настройка поддерживаемых языков
• Справка по API: