# gt: General Translation CLI tool: gt translate URL: https://generaltranslation.com/ru/docs/cli/reference/commands/translate.mdx Docs index: https://generaltranslation.com/llms.txt 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). Lottie-анимации необходимо подготовить перед последующим скачиванием, поскольку обработка их макета выполняется асинхронно. *Примечание: только для использования в 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` и `gt-vue` сканирует glob-шаблоны в `src` на наличие встроенного контента. Сюда входят компоненты [``](/docs/react/reference/components/t) и вызовы [`useGT`](/docs/react/reference/hooks/use-gt) из семейства React, а также шаблоны Vue и вызовы [`t()`](/docs/vue/reference/functions/t) на уровне модуля; также включается файл словаря. 3. Автоматически определяет стороннюю библиотеку i18n из `package.json` — `next-intl` или `i18next` (с поддержкой `i18next-icu`) — и переводит её JSON-файлы с учётом синтаксиса этой библиотеки. 4. Подготавливает собранный контент с помощью [`gt stage`](/docs/cli/reference/commands/stage): команда загружает исходные файлы, при заданном `--save-local` или [`options.saveLocal: true`](/docs/cli/reference/config#save-local) дополнительно обнаруживает и сохраняет локальные правки, а затем ставит задачи перевода в очередь. Поскольку обработка макета Lottie выполняется асинхронно, проект с файлами `.lottie` завершает работу до этого шага, если `stageTranslations` имеет значение `false`, ничего не загружая и не ставя в очередь, и предлагает перейти к раздельному процессу. 5. Скачивает результаты с помощью [`gt download`](/docs/cli/reference/commands/download). Используйте отдельные команды, чтобы выполнять подготовку и скачивание по отдельности. 6. Сохраняет переводы в кодовую базу, а при заданном `--publish` или ключе конфигурации [`publish`](/docs/cli/reference/config#publish) — также в CDN. По умолчанию CLI не синхронизирует локальные правки переводов перед началом новой работы. Передайте `--save-local`, чтобы синхронизировать их, `--force`, чтобы заново перевести всё, или `--force-download`, чтобы заново скачать результаты без повторного перевода. ## Флаги [#flags] | Параметр | Описание | Тип | Необязательно | По умолчанию | | ------------------------------- | --------------------------------------------------------------------------------------- | ---------- | ------------- | ---------------- | | `--api-key ` | Production API-ключ. | `string` | Да | `GT_API_KEY` | | `--project-id ` | ID проекта. | `string` | Да | `GT_PROJECT_ID` | | `--version-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, --no-save-local` | Включить или отключить сохранение локальных правок перед добавлением в очередь. | `boolean` | Да | `false` | | `--publish` | Опубликовать переводы в CDN. | `boolean` | Да | `false` | | `--enable-branching` | Включить отслеживание по веткам. | `boolean` | Да | — | | `--branch ` | Имя ветки вместо автоопределения. Подразумевает `--enable-branching`. | `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` и `gt-vue`. | Parameter | Description | Type | Optional | Default | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- | ------------------------------------ | | `--src ` | Glob-шаблоны для исходных файлов. | `string[]` | Да | glob-шаблоны, зависящие от фреймворка | | `--dictionary ` | Путь к файлу словаря. | `string` | Да | — | | `--tsconfig, --jsconfig ` | Путь к конфигурационному файлу TS или JS. | `string` | Да | Определяется автоматически | | `--inline` | Включать встроенный контент, например [``](/docs/react/reference/components/t) и [`useGT`](/docs/react/reference/hooks/use-gt). | `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 использует значения по умолчанию, зависящие от фреймворка. В проектах семейства React сканируются `src`, `app`, `pages` и `components`; в проектах Vue дополнительно охватываются файлы `.vue` в корне и стандартные каталоги Vue и Nuxt. Чтобы переопределить их, используйте `--src` или ключ конфигурации [`src`](/docs/cli/reference/config#src). * **Словарь:** если `--dictionary` не задан, CLI ищет `dictionary.[json|ts|js]` в `./src` и `./`. * **Локальная правка:** синхронизация локальных правок по умолчанию отключена. Передайте `--save-local` для одного запуска или задайте [`options.saveLocal`](/docs/cli/reference/config#save-local) значение `true`. * **Перезапись:** `--force` перезаписывает все существующие переводы и списывает оплату за новые; `--force-download` перезаписывает локальную правку последними переводами без повторного перевода. * **Lottie:** переведите анимации с помощью [`gt stage`](/docs/cli/reference/commands/stage), затем повторно запускайте [`gt download`](/docs/cli/reference/commands/download), пока не будут готовы все локали. См. [справочник по формату Lottie](/docs/cli/reference/formats/lottie-files). * **Тегирование:** тегирование не блокирует выполнение — если не удаётся создать тег, запуск продолжается. Передайте `--tag` без значения, чтобы использовать текущие хеш коммита Git и сообщение коммита. * **Публикация:** перед использованием `--publish` включите CDN в настройках проекта. Если CDN не включён, перевод завершится успешно, но шаг публикации завершится с предупреждением. * **Ветвление:** передайте `--enable-branching`, чтобы отслеживать переводы по веткам Git, или `--branch `, который сам включает ветвление. Если не задан ни один из флагов, CLI использует `branchOptions.enabled` из `gt.config.json`, а если он не задан — отключает ветвление. См. [Отслеживание переводов по веткам](/docs/cli/guides/branching). * **`--version-id` не действует.** Флаг разбирается, но нигде не используется: ID версий — это хеши содержимого отдельных файлов, а команды, которым нужен ID версии на уровне запуска, считывают `_versionId` из `gt.config.json`. Вместо этого задайте там [`_versionId`](/docs/cli/reference/config). * **Безопасность:** никогда не храните свой API-ключ в `gt.config.json`. CLI автоматически считывает `GT_API_KEY` и `GT_PROJECT_ID` из переменных окружения. ### История версий | Версия | Изменения | | -------- | -------------------------------------------------------------------------------------------- | | `2.20.3` | Локальные правки теперь включаются вручную; флаг `--save-local` активирует этот шаг. | | `2.16.1` | Локальные правки теперь сохраняются по умолчанию; `--no-save-local` отключает это поведение. | ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.