# gt: General Translation CLI tool: Translate
URL: https://generaltranslation.com/ru/docs/cli/translate.mdx
---
title: Translate
description: Как перевести проект
---

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

```bash
npx gt translate
```

<Callout type="error">
  **Важно:** Запустите это в вашем CI-конвейере **до** сборки приложения для продакшена.
</Callout>


## Обзор

Команда `gt translate` переводит проект: она считывает файл `gt.config.json`, чтобы определить, какие файлы нужно перевести.

Если вы используете [`gt-next`](/docs/next), [`gt-react`](/docs/react) или [`gt-react-native`](/docs/react-native), она также просканирует исходный код проекта на наличие встроенного контента (например, компонентов `<T>` и хуков `useGT`) и сгенерирует необходимые файлы перевода.
Кроме того, она включает контент файла словаря (если он указан).

Эта команда — основной способ работы с API General Translation и связанными сервисами.

<Callout type="warn">
  **Только для использования в продакшене:**

  Эта команда предназначена для продакшен-сборок и **не должна использоваться в development**.
  Перед запуском этой команды обязательно убедитесь, что вы находитесь в ветке, которая будет использоваться для продакшена.
  Укажите продакшен API-ключ (`GT_API_KEY`) и идентификатор проекта (`GT_PROJECT_ID`) как переменные окружения.
</Callout>

<Callout type="info">
  **Примечание:** требуется продакшен API-ключ. Получите его бесплатно на [generaltranslation.com](https://generaltranslation.com/dashboard) или запустите [мастер настройки](/docs/cli/init), чтобы сгенерировать его.
</Callout>

### Переведите проект [#translate]

```bash
npx gt translate
```

Команда `translate` читает файл `gt.config.json`, чтобы определить, какие файлы нужно перевести, а также ищет в исходном коде проекта контент, доступный для перевода, а затем генерирует необходимые файлы перевода.

Переводы автоматически сохраняются в кодовой базе проекта.

Подробнее см. в [документации по конфигурации](/docs/cli/reference/config#files).

<Callout type="info">
  {/* These links point to our own SDK docs intentionally — we want to show how our CLI handles these libraries, not link to the external library sites */}

  **Автоопределение:** Если вы используете [`next-intl`](/docs/next), [`react-i18next`](/docs/react) или
  [`next-i18next`](/docs/react-native), CLI автоматически определит
  вашу библиотеку i18n по файлу `package.json` и переведёт ваши
  JSON-файлы с учётом синтаксиса этой библиотеки i18n.
</Callout>


### Проверка без перевода [#validate]

```bash
npx gt translate --dry-run
```

Если вы используете [`gt-next`](/docs/next), [`gt-react`](/docs/react), или [`gt-react-native`](/docs/react-native), вы можете использовать это для проверки компонентов `<T>` и файла словаря в вашем проекте без генерации переводов.

***


## Флаги

| Параметр                        | Описание                                                                                    | Тип        | По умолчанию                                                                                                                |
| ------------------------------- | ------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--api-key`                     | Укажите Production API-ключ                                                                 | `string`   |                                                                                                                             |
| `--project-id`                  | Укажите идентификатор проекта                                                               | `string`   |                                                                                                                             |
| `--version-id`                  | Укажите идентификатор версии (по умолчанию — хеш контента)                                  | `string`   |                                                                                                                             |
| `--config <path>`               | Укажите путь к config file GT                                                               | `string`   | `"gt.config.json"`                                                                                                          |
| `--tsconfig, --jsconfig <path>` | Укажите путь к TS- или JS-config file                                                       | `string`   |                                                                                                                             |
| `--src <paths>`                 | Разделённые пробелами glob-шаблоны для исходных файлов (относительно корня)                 | `[string]` | `['src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}']` |
| `--dictionary <path>`           | Укажите путь к файлу словаря                                                                | `string`   |                                                                                                                             |
| `--inline`                      | Включать инлайн-теги `<T>` в дополнение к словарю                                           | `boolean`  | `true`                                                                                                                      |
| `--timeout`                     | Тайм-аут запроса перевода в секундах                                                        | `number`   | `900`                                                                                                                       |
| `--new, --locales <locales>`    | Локали, на которые нужно перевести (добавляются к `locales` в `gt.config.json`)             | `[string]` |                                                                                                                             |
| `--default-locale <locale>`     | Исходная локаль проекта                                                                     | `string`   | `en`                                                                                                                        |
| `--ignore-errors`               | Игнорировать ошибки и принудительно выполнять перевод для валидного контента                | `flag`     | `false`                                                                                                                     |
| `--dry-run`                     | Выполнить валидацию без перевода                                                            | `flag`     | `false`                                                                                                                     |
| `--force`                       | Принудительно выполнить повторный перевод всего контента                                    | `flag`     | `false`                                                                                                                     |
| `--force-download`              | Принудительно скачать все переводы                                                          | `flag`     | `false`                                                                                                                     |
| `--save-local`                  | Обнаружить и сохранить локальные правки перед постановкой переводов в очередь               | `flag`     | `false`                                                                                                                     |
| `--enable-branching`            | Включить ветвление для проекта                                                              | `flag`     | `false`                                                                                                                     |
| `--branch <branch>`             | Укажите пользовательское имя ветки для переводов                                            | `string`   |                                                                                                                             |
| `--disable-branch-detection`    | Отключить автоматическое определение ветки                                                  | `flag`     | `false`                                                                                                                     |
| `--tag [value]`                 | Пометить этот запуск перевода (автоматически определяется из git, если значение не указано) | `string`   |                                                                                                                             |
| `-m, --message <message>`       | Сообщение, которое нужно прикрепить к тегу перевода                                         | `string`   |                                                                                                                             |
| `--publish`                     | Опубликовать переводы в CDN после перевода                                                  | `flag`     | `false`                                                                                                                     |
| `--remote-name <name>`          | Укажите пользовательское имя remote для определения ветки                                   | `string`   | `"origin"`                                                                                                                  |

<Callout type="warn">
  **Безопасность:** Не добавляйте API-ключ в файл `gt.config.json`! Вместо этого задайте его как переменную окружения. CLI автоматически считывает `GT_API_KEY`, если она задана.
</Callout>

### Основные флаги

| Флаг                 | Описание                                                                                                                                             |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dry-run`          | Разбирает и проверяет проект без обращения к API GT. Полезно для проверки кодовой базы.                                                              |
| `--force`            | Заново переводит весь контент, перезаписывая существующие переводы. Все локальные изменения будут потеряны. За новые переводы будет взиматься плата. |
| `--force-download`   | Повторно загружает все переводы, перезаписывая локальные изменения. Не запускает повторный перевод.                                                  |
| `--save-local`       | Обнаруживает и сохраняет локальные правки в файлах перевода перед постановкой в очередь. См. [`save-local`](/docs/cli/save-local).                  |
| `--enable-branching` | Отслеживает переводы отдельно для разных веток Git. См. [ветвление](/docs/cli/branching).                                                            |
| `--tag`              | Помечает запуск перевода человекочитаемым идентификатором для отслеживания версий. См. [тегирование](#tagging).                                      |
| `-m, --message`      | Добавляет к тегу перевода поясняющее сообщение. См. [тегирование](#tagging).                                                                         |
| `--publish`          | Публикует переводы в CDN для загрузки во время выполнения. См. [публикация в CDN](#publishing-to-the-cdn).                                           |

### Файл конфигурации

При первом запуске CLI попытается создать файл `gt.config.json` в корне проекта. Подробнее о конфигурации читайте [здесь](/docs/cli/reference/config).

## Важные рекомендации

### Источники контента

Команда `translate` рекурсивно ищет в вашем проекте контент, пригодный для перевода.

По умолчанию поиск выполняется в следующих каталогах:

* `./src`
* `./app`
* `./pages`
* `./components`

Вы можете указать другие каталоги с помощью флага `--src` или изменив свойство `src` в файле [`gt.config.json`](/docs/cli/reference/config).

### Перезапись переводов

По умолчанию CLI не перезаписывает локальные правки в переводах, если исходный контент не изменился.

Чтобы заново перевести контент, который уже был переведён, используйте `--force`.

<Callout type="warn">
  **Внимание:** `--force` **перезапишет все существующие переводы и создаст новые**. Все локальные изменения будут потеряны. С вас будет списана плата за новые переводы.
</Callout>

Чтобы повторно скачать переводы без повторного перевода, используйте `--force-download`.

<Callout type="warn">
  **Внимание:** `--force-download` перезапишет локальные правки в переводах и загрузит самые актуальные переводы. Повторный перевод контента выполняться не будет.
</Callout>

### Тегирование [#tagging]

Используйте флаги `--tag` и `-m`, чтобы помечать запуски перевода понятными идентификаторами — так будет проще отслеживать версии и различать их на панели управления.

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

```bash
npx gt translate --tag v2.1.0
```


#### Тег с пользовательским идентификатором и сообщением

```bash
npx gt translate --tag v2.1.0 -m "Added checkout page translations"
```


#### Автотег из Git

Передайте `--tag` без значения, чтобы автоматически использовать хеш текущего коммита Git как id тега, а сообщение коммита — как сообщение тега:

```bash
npx gt translate --tag
```

Вы можете переопределить сообщение коммита, указав своё:

```bash
npx gt translate --tag -m "Release 2.1 translations"
```


#### Тегирование только по сообщению

Если передать `-m` без `--tag`, тег будет автоматически сгенерирован на основе хеша текущего коммита Git (или случайного идентификатора, если вы не в git-репозитории):

```bash
npx gt translate -m "Weekly translation update"
```

<Callout type="info">
  Добавление тегов не блокирует процесс — если создать тег не удаётся, запуск перевода всё равно продолжается в обычном режиме.
</Callout>


### Публикация в CDN [#publishing-to-the-cdn]

По умолчанию `gt translate` сохраняет файлы перевода локально в вашей кодовой базе. Используйте флаг `--publish`, чтобы также опубликовать переводы в CDN General Translation и включить их загрузку во время выполнения без добавления файлов в бандл приложения.

```bash
npx gt translate --publish
```

Это полезно для проектов `gt-next`, которые загружают переводы из CDN во время выполнения, а не из локальных файлов.

<Callout type="warn">
  **Необходимо включить CDN:** Перед использованием `--publish` включите CDN в настройках проекта на [generaltranslation.com/dashboard](https://generaltranslation.com/dashboard). Если CDN не включён, команда успешно выполнит перевод, но не сможет опубликовать результаты и выдаст предупреждение.
</Callout>

Вы можете использовать `--publish` вместе с выводом в локальные файлы — переводы будут сохранены локально *и* опубликованы в CDN:

```bash
npx gt translate --publish
```

### Файл словаря

Команда `translate` автоматически обнаруживает файл словаря в вашем проекте.

По умолчанию она ищет файл с именем `dictionary.[json|ts|js]` в:

* `./src`
* `./`

Вы можете указать другой файл словаря с помощью флага `--dictionary`
или изменить свойство `dictionary` в файле [`gt.config.json`](/docs/cli/reference/config).