# gt: General Translation CLI tool: Настройка CLI
URL: https://generaltranslation.com/ru/docs/cli/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Как настроить gt.config.json для General Translation с локалями, файлами и параметрами хранения.

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

*Примечание: в этом руководстве рассматриваются распространённые варианты настройки. Все доступные поля см. в [справочнике по конфигурации](/docs/cli/reference/config).*

## Создайте файл конфигурации [#create]

Создать `gt.config.json` можно тремя способами. Выберите тот, который лучше всего подходит для вашего workflow.

### a) Запустите полный мастер настройки

Запустите [`gt init`](/docs/cli/reference/commands/init), чтобы определить используемый фреймворк, настроить файлы и при желании создать проект и ключ среды выполнения для разработки. Если на каком-либо шаге потребуется вход в аккаунт, мастер предложит его выполнить. Передайте [флаги](/docs/cli/reference/commands/init#flags), чтобы заранее ответить на вопросы мастера, или запустите его в неинтерактивном (headless) режиме.

```bash
npx gt init
```

В монорепозитории запускайте команду из приложения, которое хотите локализовать, а не из корня рабочего пространства. Для приложений Vite React мастер устанавливает `gt-react`, добавляет вызов [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) перед существующей точкой входа приложения и настраивает загрузку переводов локально или через CDN.

### b) Настройка без этапа настройки React

Выполните [`gt configure`](/docs/cli/reference/commands/configure), чтобы создать или обновить `gt.config.json` без экспериментального переписывания кода React-фреймворка. В остальном процесс настройки совпадает с полным мастером: команда может сгенерировать загрузчики, установить CLI, предложить выполнить вход и подготовить учётные данные для разработки.

```bash
npx gt configure
```

### c) Создайте его вручную

Создайте файл самостоятельно и добавьте ссылку на `$schema` для валидации и автодополнения в редакторе.

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}
```

## Укажите локали [#locales]

Укажите в `defaultLocale` язык, на котором написан исходный контент, а в `locales` перечислите целевые языки.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es", "ja"]
}
```

Оба варианта используют стандартные коды локалей, такие как `en`, `en-US` или `zh`. Полный список см. в разделе [поддерживаемые локали](/docs/platform/dashboard/reference/supported-locales).

Чтобы использовать собственный алиас локали — например, `cn` вместо `zh`, — добавьте запись `customMapping`, которая указывает на официальный код. Затем указывайте этот алиас везде, где выбираете эту локаль в `defaultLocale` или `locales`.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["cn", "fr"],
  "customMapping": {
    "cn": { "code": "zh" }
  }
}
```

## Выберите, какие файлы переводить [#files]

Добавьте объект `files` с ключом для каждого типа файлов, который нужно переводить. Для большинства типов указывается массив `include` с glob-шаблонами, использующими заполнитель `[locale]` для поиска исходных файлов и сохранения переведённых. Исключение — [каталоги `.xcstrings`](/docs/cli/reference/formats/xcstrings-files), поскольку все локали хранятся в одном файле, который обновляется на месте.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["locales/[locale]/**/*.json"]
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"]
    }
  }
}
```

CLI заменяет `[locale]` на `defaultLocale` при поиске source files, а при сохранении переводов — на код каждой целевой локали. Параметры для каждого типа описаны в разделе [Форматы файлов](/docs/cli/reference/formats/gt-jsx-files), а расширенные правила сопоставления — в разделе [`include`](/docs/cli/reference/config#files).

## Выберите, где хранятся переводы [#storage]

Если вы используете `gt-next`, `gt-react` или `gt-react-native`, решите, как будут поставляться переводы.

* **Сохраняйте локально**, чтобы включить переводы в бандл приложения. Добавьте запись `gt` и укажите путь `output`, включающий `[locale]`.
* **Публикуйте в CDN**, чтобы загружать переводы во время выполнения, а не включать их в бандл. Установите `publish` в `true`.

```json title="gt.config.json"
{
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    }
  }
}
```

(См. [публикацию в CDN](/docs/cli/reference/config#cdn-publishing), чтобы управлять публикацией глобально, для отдельных файлов или команд).

## Добавьте учетные данные [#credentials]

### a) Вход для локальной работы с CLI

1. Выполните [`gt login`](/docs/cli/reference/commands/login) и подтвердите доступ в браузере. Чтобы проверить учётную запись, используйте [`gt whoami`](/docs/cli/reference/commands/whoami), а чтобы выйти — [`gt logout`](/docs/cli/reference/commands/logout).
2. Привяжите приложение к проекту: укажите [`projectId`](/docs/cli/reference/config#project-id) в существующем `gt.config.json` или задайте переменную `GT_PROJECT_ID`. Сам по себе вход не выбирает и не создаёт проект. Если вы хотите выбрать или создать проект в пошаговом режиме, а не привязывать его вручную, используйте [`gt init`](/docs/cli/reference/commands/init).
3. Выполните [`gt translate`](/docs/cli/reference/commands/translate). У вашей учётной записи должно быть разрешение на каждую запрашиваемую операцию.

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

### b) Используйте явный ключ для CI

Закоммитьте файл конфигурации и передайте `GT_API_KEY` через настройки секретов вашего CI-провайдера. Укажите ID проекта в конфигурации или в переменных окружения. Вход в систему, в том числе с `--no-browser`, требует утверждения человеком. [`gt init`](/docs/cli/reference/commands/init) в headless-режиме выполняется без участия пользователя, только если флаги задают ответы на все вопросы и входить в систему не требуется.

```bash
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

Создайте [пользовательский ключ проекта](/docs/platform/dashboard/reference/api-keys#create-project-keys) или воспользуйтесь командой [`gt api-key create`](/docs/cli/reference/commands/api-key-create) с явно заданными разрешениями. Выдайте разрешения на весь рабочий процесс: чтение и скачивание файлов, запись и загрузку файлов, постановку переводов в очередь, а также доступ к контексту, если он используется. Для конвейера перевода недостаточно ключа среды выполнения, который позволяет только генерировать переводы. Никогда не храните API-ключи в `gt.config.json`: стандартная проверка настроек CLI их отклоняет.

### Приоритет учётных данных и файлы окружения

Если явный ключ для инструментов не передан, хостинговые команды сначала используют `--api-key`, затем непустую переменную `GT_API_KEY`, а затем сохранённый вход. Если явно указанный ключ недействителен или у него недостаточно прав, команда никогда не переключается на сохранённый вход. `GT_DEV_API_KEY` и его варианты с публичным префиксом — это настройки среды выполнения, а не учётные данные для управления через CLI. Чтобы использовать сохранённый вход, удалите ненужные ключи для инструментов как из окружения процесса, так и из загружаемых env-файлов: вход в систему их не удаляет.

При запуске исполняемый файл загружает `.env`, затем `.env.local` с переопределением, затем `.env.production` с переопределением. Два последних файла могут заменить уже экспортированный ключ. О привязке проекта и проверке конфликтов см. [`projectId`](/docs/cli/reference/config#project-id).

### Ключи среды выполнения для разработки

[`gt init`](/docs/cli/reference/commands/init) может создать ключ только с правом `project:translations:generate` и записать его в игнорируемый файл `.env.local`, используя имена переменных вашего фреймворка. Этот ключ не заменяет `GT_API_KEY`. (Настройка среды выполнения описана в разделе [Учётные данные Next.js](/docs/react/nextjs/config#credentials).)

<Callout type="warn">
  Никогда не включайте API-ключи в развёртываемые браузерные или мобильные бандлы — даже ключи, которые разрешают только генерацию. (См. [защиту файлов при init](/docs/cli/reference/commands/init#notes).)
</Callout>

## Next steps

- /docs/cli/guides/generating-translations
- /docs/cli/guides/managing-translations
- /docs/cli/guides/using-auto-jsx
- /docs/cli/guides/branching

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.