# gt: General Translation CLI tool: gt translate URL: https://generaltranslation.com/ru/docs/cli/reference/commands/translate.mdx --- title: gt translate description: Перевод проекта через API General Translation. Справочник API для команды `gt translate`. --- Переводит ваш проект. Команда читает `gt.config.json`, чтобы найти нужные файлы, сканирует исходный код на наличие встроенного контента при использовании библиотеки фреймворка, включает ваш словарь и сохраняет переводы в кодовую базу или CDN. Это основная команда для работы с API General Translation. Запускайте её в CI перед production-сборкой. Полный workflow описан в разделе [Generating translations](/docs/cli/guides/generating-translations). Под капотом `translate` выполняет `stage` и скачивание за один шаг; чтобы запускать эти части по отдельности, используйте [`gt stage`](/docs/cli/reference/commands/stage), [`gt upload`](/docs/cli/reference/commands/upload), [`gt enqueue`](/docs/cli/reference/commands/enqueue) и [`gt download`](/docs/cli/reference/commands/download). *Примечание: только для использования в Production. Задайте production `GT_API_KEY` и `GT_PROJECT_ID` как переменные окружения и никогда не храните свой API-ключ в `gt.config.json`.* ```bash npx gt translate ``` ## Как это работает [#how-it-works] 1. Читает `gt.config.json`, чтобы определить целевые локали, файлы для перевода и пути вывода. 2. Для проектов `gt-next`, `gt-react`, `gt-react-native` и `gt-tanstack-start` сканирует glob-шаблоны в `src` на наличие встроенного контента — компонентов [``](/docs/react/reference/components/t) и вызовов [`useGT`](/docs/react/reference/hooks/use-gt) — и включает файл словаря. 3. Автоматически определяет стороннюю библиотеку i18n из `package.json` — `next-intl` или `i18next` (с поддержкой `i18next-icu`) — и переводит её JSON-файлы с учётом синтаксиса этой библиотеки. 4. Подготавливает собранный контент и загружает результаты за один шаг. Внутри это [`gt stage`](/docs/cli/reference/commands/stage), а затем [`gt download`](/docs/cli/reference/commands/download); если нужно выполнить эти части по отдельности, используйте отдельные команды. 5. Сохраняет переводы в кодовую базу, а при заданном `--publish` или ключе конфигурации [`publish`](/docs/cli/reference/config#publish) — также в CDN. По умолчанию CLI не перезаписывает изменения в локальных переводах, если исходный контент не изменился. Используйте `--force`, чтобы заново перевести всё, или `--force-download`, чтобы заново скачать результаты без повторного перевода. ## Флаги [#flags] | Параметр | Описание | Тип | Необязательно | По умолчанию | | ---------------------------- | --------------------------------------------------------------------------------------- | ---------- | ------------- | ---------------- | | `--api-key ` | Production API-ключ. | `string` | Да | `GT_API_KEY` | | `--project-id ` | ID проекта. | `string` | Да | `GT_PROJECT_ID` | | `--version-id ` | ID версии для запуска. | `string` | Да | Хеш контента | | `-c, --config ` | Путь к конфигурационному файлу. | `string` | Да | `gt.config.json` | | `--default-locale ` | Исходная локаль проекта. | `string` | Да | `en` | | `--locales ` | Дополнительные целевые локали, добавляемые к locales из конфигурации. | `string[]` | Да | — | | `--timeout ` | Тайм-аут ожидания перевода в секундах. | `number` | Да | `900` | | `--dry-run` | Выполнить разбор и проверку без вызова API. | `boolean` | Да | `false` | | `--force` | Повторно перевести весь контент, перезаписав существующие переводы. | `boolean` | Да | `false` | | `--force-download` | Повторно скачать все переводы, перезаписав локальные изменения. | `boolean` | Да | `false` | | `--save-local` | Сохранить локальные изменения перед добавлением в очередь. | `boolean` | Да | `false` | | `--publish` | Опубликовать переводы в CDN. | `boolean` | Да | `false` | | `--enable-branching` | Включить отслеживание по веткам. | `boolean` | Да | `false` | | `--branch ` | Имя ветки вместо автоопределения. | `string` | Да | — | | `--disable-branch-detection` | Использовать только указанную ветку, без определения связей между ветками. | `boolean` | Да | `false` | | `--remote-name ` | Git-remote, используемый для определения ветки. | `string` | Да | `origin` | | `--omit-config-ids` | Не записывать `_versionId` или `_branchId` в `gt.config.json`. | `boolean` | Да | — | | `--tag [value]` | Пометить запуск тегом; если значение не указано, оно автоматически определяется из git. | `string` | Да | — | | `-m, --message ` | Сообщение, прикреплённое к тегу перевода. | `string` | Да | — | ### Флаги сканирования исходников [#source] Эти флаги применяются при сканировании исходного кода в проектах `gt-next`, `gt-react`, `gt-react-native` и `gt-tanstack-start`. | Parameter | Description | Type | Optional | Default | | ------------------------------- | --------------------------------------------------------------------- | ---------- | -------- | ------------------------------------------------ | | `--src ` | Glob-шаблоны для исходных файлов. | `string[]` | Да | glob-шаблоны `src`, `app`, `pages`, `components` | | `--dictionary ` | Путь к файлу словаря. | `string` | Да | — | | `--tsconfig, --jsconfig ` | Путь к файлу конфигурации TS или JS. | `string` | Да | Определяется автоматически | | `--inline` | Включать встроенный контент, например `` и `useGT`. | `boolean` | Да | `true` | | `--ignore-errors` | Игнорировать ошибки, найденные при сканировании встроенного контента. | `boolean` | Да | `false` | ### Экспериментальные флаги [#experimental] | Параметр | Описание | Тип | Необязательно | По умолчанию | | ----------------------------------------- | -------------------------------------------------------------------------------------------- | --------- | ------------- | ------------ | | `--experimental-localize-static-urls` | Локализует URL-адреса в переведённых файлах `md`/`mdx`. | `boolean` | Да | `false` | | `--experimental-hide-default-locale` | Убирает локаль по умолчанию из локализованных путей. | `boolean` | Да | `false` | | `--experimental-flatten-json-files` | Объединяет JSON-файлы в один файл. | `boolean` | Да | `false` | | `--experimental-localize-static-imports` | Локализует статические импорты в файлах `md`/`mdx`. | `boolean` | Да | `false` | | `--experimental-localize-relative-assets` | Переписывает относительные URL-адреса графических ресурсов в переведённых файлах `md`/`mdx`. | `boolean` | Да | `false` | | `--experimental-clear-locale-dirs` | Очищает каталоги локалей перед скачиванием. | `boolean` | Да | `false` | ## Пример [#example] ```bash # Перевод с использованием gt.config.json, GT_API_KEY и GT_PROJECT_ID берутся из окружения npx gt translate # Разбор и валидация проекта без обращения к API npx gt translate --dry-run # Сохранение переводов локально и публикация на CDN для загрузки в runtime npx gt translate --publish # Тег для запуска, чтобы его было легко найти в панели управления npx gt translate --tag v2.1.0 -m "Added checkout page translations" ``` ## Другие примечания [#notes] * **Источники Content:** по умолчанию CLI сканирует `src`, `app`, `pages` и `components`. Чтобы переопределить этот список, используйте `--src` или ключ конфигурации [`src`](/docs/cli/reference/config#src). * **Словарь:** если `--dictionary` не задан, CLI ищет `dictionary.[json|ts|js]` в `./src` и `./`. * **Перезапись:** `--force` перезаписывает все существующие переводы и списывает оплату за новые; `--force-download` перезаписывает local edits последними переводами без повторного перевода. * **Тегирование:** тегирование не блокирует выполнение — если не удаётся создать тег, запуск продолжается. Передайте `--tag` без значения, чтобы использовать текущие хеш коммита Git и сообщение коммита. * **Публикация:** перед использованием `--publish` включите CDN в настройках проекта. Если CDN не включён, перевод завершится успешно, но шаг публикации завершится с предупреждением. * **Ветвление:** передайте `--enable-branching`, чтобы отслеживать переводы по веткам Git. См. [Отслеживание переводов по веткам](/docs/cli/guides/branching). * **Безопасность:** никогда не храните свой API-ключ в `gt.config.json`. CLI автоматически считывает `GT_API_KEY` и `GT_PROJECT_ID` из переменных окружения.