# gt: General Translation CLI tool: Конфигурация
URL: https://generaltranslation.com/ru/docs/cli/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Настройка CLI General Translation с помощью файла gt.config.json. Справочник API для gt.config.json.
Файл `gt.config.json` определяет, что именно переводит CLI и куда сохраняются результаты. Разместите его в корневой директории проекта. Создать его можно с помощью [`gt init`](/docs/cli/reference/commands/init) или [`gt configure`](/docs/cli/reference/commands/configure), либо написать вручную.
*Примечание: Добавьте [JSON Schema](https://assets.gtx.dev/config-schema.json) с ключом `$schema`, чтобы редактор поддерживал валидацию и автодополнение. Опубликованная схема отстаёт и не включает часть допустимых ключей файлов, в том числе `pot`, `html`, `txt`, `twilioContentJson`, `lottie`, `dotStrings`, `dotStringsdict`, `androidStrings`, `xcstrings` и `srt`, а также не содержит `fonts` и `options.saveLocal`. Редакторы могут помечать неподдерживаемые схемой поля, пока схема не будет обновлена.*
## Параметры [#options]
| Параметр | Описание | Тип | Необязательно | По умолчанию |
| ------------------------------------ | -------------------------------------------------------------------------------- | ---------- | ------------- | --------------------- |
| [`projectId`](#project-id) | проект, используемый для API и процессов перевода. | `string` | Да | `GT_PROJECT_ID` |
| [`baseUrl`](#base-url) | Базовый URL для запросов к General Translation API. | `string` | Да | `https://api.gtx.dev` |
| [`defaultLocale`](#default-locale) | Локаль, на которой написан исходный контент. | `string` | Да | `en` |
| [`locales`](#locales) | Целевые локали для перевода. | `string[]` | Да | — |
| [`files`](#files) | Какие файлы переводить и где их сохранять. | `object` | Да | — |
| [`fonts`](#fonts) | Файлы шрифтов, доступные задачам перевода Lottie. | `object` | Да | — |
| [`publish`](#publish) | Публиковать переведённые файлы в CDN. | `boolean` | Да | `false` |
| [`stageTranslations`](#stage) | Использовать рабочий процесс с подготовкой версий перед скачиванием переводов. | `boolean` | Да | `false` |
| [`requiresReview`](#requires-review) | Политика обязательной проверки по умолчанию для всех переведённых файлов. | `boolean` | Да | `false` |
| [`src`](#src) | Glob-шаблоны исходных файлов для поиска встроенного контента. | `string[]` | Да | Зависит от фреймворка |
| [`dictionary`](#dictionary) | Путь к файлу словаря. | `string` | Да | — |
| [`branchOptions`](#branch-options) | Настройки отслеживания переводов по веткам. | `object` | Да | — |
| [`customMapping`](#custom-mapping) | Алиасы локалей и переопределения свойств. | `object` | Да | — |
| [`options.saveLocal`](#save-local) | Обнаруживать и отправлять локальные правки перевода перед постановкой в очередь. | `boolean` | Да | `false` |
## `projectId` [#project-id]
**Type** `string` · **Optional** · **Default** `GT_PROJECT_ID`
Проект, используемый для API и процессов перевода. Флаг `--project-id` переопределяет значение переменной окружения, но должен совпадать с `projectId`, если тот указан в конфигурации.
```json title="gt.config.json"
{
"projectId": "project-id"
}
```
## `baseUrl` [#base-url]
**Type** `string` · **Optional** · **Default** `https://api.gtx.dev`
Origin API, который используется в запросах CLI, включая [`gt api`](/docs/cli/reference/commands/api). Задавайте это значение только в том случае, если в вашем рабочем процессе используется собственный эндпоинт General Translation API.
```json title="gt.config.json"
{
"baseUrl": "https://api.gtx.dev"
}
```
## `defaultLocale` [#default-locale]
**Тип** `string` · **Необязательно** · **По умолчанию** `en`
Локаль, на которой написан исходный контент. Это локаль, с которой CLI выполняет перевод, а также резервная локаль при использовании `gt-next`, `gt-react` или `gt-vue`.
```json title="gt.config.json"
{
"defaultLocale": "en"
}
```
## `locales` [#locales]
**Тип** `string[]` · **Необязательно** · **По умолчанию** —
Целевые локали, на которые будет переводиться контент. Список допустимых кодов см. в разделе [поддерживаемые локали](/docs/platform/dashboard/reference/supported-locales). Инициализаторы фреймворков, принимающие список локалей, также используют их как локали, которые поддерживает ваше приложение.
```json title="gt.config.json"
{
"locales": ["fr", "es", "ja"]
}
```
## `files` [#files]
**Тип** `object` · **Необязательно** · **По умолчанию** —
Объект, содержащий по одному ключу для каждого типа файла, который нужно перевести. Каждому типу соответствует объект с настройками. См. раздел [Форматы файлов](/docs/cli/reference/formats/gt-jsx-files) с рекомендациями для каждого типа.
### Поддерживаемые типы файлов
| Ключ | Тип файла | Ссылка |
| ------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `gt` | Файлы General Translation для `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start` и `gt-vue`. | [GT](/docs/cli/reference/formats/gt-jsx-files) |
| `json` | JSON-файлы. | [JSON](/docs/cli/reference/formats/json-files) |
| `yaml` | Файлы YAML (`.yaml` и `.yml`). | [YAML](/docs/cli/reference/formats/yaml-files) |
| `pot` | Файлы gettext PO/POT. | [PO / POT](/docs/cli/reference/formats/po-pot-files) |
| `mdx` | MDX-файлы. | [MDX и Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `md` | Файлы Markdown. | [MDX и Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `ts` | Файлы TypeScript. | [TypeScript и JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `js` | Файлы JavaScript. | [TypeScript и JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `html` | Файлы HTML. | [HTML](/docs/cli/reference/formats/html-files) |
| `txt` | Текстовые файлы. | [Обычный текст](/docs/cli/reference/formats/plain-text-files) |
| `srt` | Файлы субтитров SubRip (`.srt`). | [SRT](/docs/cli/reference/formats/srt-files) |
| `twilioContentJson` | Шаблоны Twilio Content JSON. | — |
| `lottie` | Файлы анимации dotLottie (`.lottie`). | [Lottie](/docs/cli/reference/formats/lottie-files) |
| `xcstrings` | Каталоги строк Apple (`.xcstrings`). | [.xcstrings](/docs/cli/reference/formats/xcstrings-files) |
| `dotStrings` | Таблицы `.strings`, по одной на локаль в каталоге `.lproj`. | [.strings](/docs/cli/reference/formats/dot-strings-files) |
| `dotStringsdict` | Файлы множественных форм `.stringsdict`, по одному на локаль в каталоге `.lproj`. | [.stringsdict](/docs/cli/reference/formats/dot-stringsdict-files) |
| `androidStrings` | Файлы ресурсов Android `strings.xml`. | [Android strings.xml](/docs/cli/reference/formats/android-strings-files) |
Для `dotStrings` и `dotStringsdict` требуется `gt` версии 2.18.1 или новее, для `androidStrings` — `gt` версии 2.19.0 или новее, для `xcstrings` — `gt` версии 2.21.0 или новее, а для `srt` — `gt` версии 2.22.2 или новее.
**Изменено в v2.18.1:** Ключи файлов Apple изменились с `strings` и `stringsdict` на `dotStrings` и `dotStringsdict`. Прежние ключи в текущих версиях не распознаются.
### Ключи типов файлов
Каждый тип файла поддерживает следующие ключи.
* `include` — массив glob-шаблонов, соответствующих файлам для перевода. Используйте заполнитель `[locale]`: CLI заменяет его на `defaultLocale`, чтобы найти исходные файлы, и на каждый целевой код, чтобы сохранить переводы. Обязательно для всех типов, кроме `gt`.
* `exclude` — массив glob-шаблонов для исключения. Заполнитель `[locale]` здесь необязателен; используйте `[locales]`, чтобы исключить путь для всех локалей.
* `transform` — переопределяет имена выходных файлов. Строка с подстановочным символом `*` переопределяет расширение (например, `*.[locale].json`). Объект с `match` и `replace` поддерживает группы захвата regex и заполнители локалей в разделе [заполнителе локали](#locale-placeholders).
* `transformationFormat` — выводит переведённые файлы в формате, отличном от исходного. Например, источники `pot` с `"transformationFormat": "PO"` создают файлы `.po`.
* `requiresReview` — делает переведённые файлы доступными только после ручной проверки. Принимает `true`/`false` или объект с glob-массивами `include` и `exclude`, где `exclude` имеет приоритет.
* `output` — только для файлов `gt`, локальный путь сохранения с заполнителем `[locale]`, например `public/i18n/[locale].json`. Обязателен, когда workflow Locadex использует **Preserve local edits** без публикации на CDN верхнего уровня; см. [Сохранение локальных правок в Locadex](#locadex-requirements).
* `parsingFlags` — только для файлов `gt`, флаги, управляющие разбором встроенного контента. См. [`autoderive`](/docs/cli/guides/using-autoderive) и [автоматическая инъекция JSX](/docs/cli/guides/using-auto-jsx).
```json title="gt.config.json"
{
"files": {
"gt": {
"output": "public/i18n/[locale].json"
},
"mdx": {
"include": ["content/docs/[locale]/**/*.mdx"],
"transform": "*.[locale].mdx"
},
"json": {
"include": ["resources/[locale]/**/*.json"],
"exclude": ["resources/[locale]/exclude/**/*.json"]
}
}
}
```
### Заполнители локали [#locale-placeholders]
Значение `replace` объекта `transform` поддерживает заполнители `{...}`, которые подставляются из свойств целевой локали. Нераспознанные имена сохраняются в output как буквальный текст.
| Заполнитель | Описание | Пример для `pt-BR` |
| -------------------- | ------------------------------------------------------------------------------------------ | ---------------------- |
| `{locale}` | Локаль в точности в том виде, как указано в [`locales`](#locales). `{localeCode}` — алиас. | `pt-BR` |
| `{localeName}` | Английское название локали, включая регион. | `Brazilian Portuguese` |
| `{localeNativeName}` | Название локали на её языке, включая регион. | `português (Brasil)` |
| `{languageCode}` | Подтег языка. | `pt` |
| `{regionCode}` | Подтег региона. | `BR` |
| `{scriptCode}` | Подтег системы письма. | `Latn` |
| `{minimizedCode}` | Самая короткая однозначная форма тега. | `pt` |
| `{maximizedCode}` | Полностью развёрнутый тег, включая систему письма. | `pt-Latn-BR` |
| `{emoji}` | Эмодзи флага, соответствующий локали. | 🇧🇷 |
Также принимаются по имени остальные поля [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties), включая `languageName`, `nativeLanguageName`, `regionName`, `nativeRegionName`, `scriptName`, `nativeScriptName`, `nameWithRegionCode`, `nativeNameWithRegionCode`, `maximizedName`, `nativeMaximizedName`, `minimizedName` и `nativeMinimizedName`.
`{locale}` использует написание из вашей конфигурации, а не каноническую форму BCP-47, поэтому для локали, настроенной как `fr-ca`, будет получено `fr-ca`, а не `fr-CA`. Это соответствует заполнителю `[locale]` в `include`, `exclude` и `output`, поэтому пути к файлам и локализованные URL совпадают. Если вместо этого нужен нормализованный тег, используйте `{minimizedCode}`, `{maximizedCode}` или `{regionCode}`.
Единственное исключение — [`androidStrings`](/docs/cli/reference/formats/android-strings-files), где оба заполнителя разворачиваются в квалификатор каталога ресурсов Android: `fr-CA` превращается в `fr-rCA`, поскольку Android завершает build с ошибкой, если не может разобрать имя каталога `values-*`.
```json title="gt.config.json"
{
"files": {
"json": {
"include": ["locales/[locale]/**/*.json"],
"transform": {
"match": "locales/(.*)/(.*)\\.json",
"replace": "locales/{locale}/$2.{languageCode}.json"
}
}
}
}
```
## `fonts` [#fonts]
**Тип** `object` · **Необязательно** · **По умолчанию** —
Файлы шрифтов, которые нужно загрузить до запуска задач перевода. Используйте glob-шаблоны `include` и необязательный `exclude`, пути в которых разрешаются относительно корня проекта. Указывайте файлы `.ttf` и `.otf`; CLI считывает их как двоичные данные и загружает в качестве постоянных ресурсов Organization для обработки макета Lottie.
| Свойство | Описание | Тип | Необязательно | По умолчанию |
| --------- | --------------------------------------- | ---------- | ------------- | ------------ |
| `include` | Glob-шаблоны для загрузки шрифтов. | `string[]` | Нет | — |
| `exclude` | Glob-шаблоны для исключения совпадений. | `string[]` | Да | `[]` |
```json title="gt.config.json"
{
"fonts": {
"include": ["public/fonts/**/*.{ttf,otf}"],
"exclude": ["public/fonts/legacy/**"]
}
}
```
CLI синхронизирует соответствующие шрифты перед выполнением [`gt stage`](/docs/cli/reference/commands/stage), [`gt upload`](/docs/cli/reference/commands/upload), [`gt enqueue`](/docs/cli/reference/commands/enqueue) и [`gt translate`](/docs/cli/reference/commands/translate), если эти команды ставят новую работу в очередь. Если включён параметр `stageTranslations`, [`gt translate`](/docs/cli/reference/commands/translate) только скачивает подготовленную версию и не синхронизирует шрифты. При сбое синхронизации шрифтов выводится предупреждение, но перевод не прерывается; обработка Lottie продолжается с резервными шрифтами. Сведения о проверке и хранении шрифтов см. в разделе [Загрузка ресурсов проекта](/docs/platform/openapi/reference/project/upload-assets).
## `publish` [#publish]
**Тип** `boolean` · **Необязательный** · **По умолчанию** `false`
Если указано `true`, переведённые файлы публикуются в CDN General Translation после [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload) или [`save-local`](/docs/cli/reference/commands/save-local). Переводы Lottie по-прежнему доступны только через API и скачивания CLI; настройка `publish` не делает файлы `.lottie` доступными из CDN. См. раздел [публикация в CDN](#cdn-publishing), чтобы управлять этим для отдельных файлов и команд.
```json title="gt.config.json"
{
"publish": true
}
```
## `stageTranslations` [#stage]
**Тип** `boolean` · **Необязательно** · **По умолчанию** `false`
Если `true`, CLI скачивает только версии, отправленные с помощью [`gt stage`](/docs/cli/reference/commands/stage). CLI автоматически устанавливает это значение при первом запуске [`gt stage`](/docs/cli/reference/commands/stage). Используйте рабочий процесс с подготовкой версий для ручной проверки и асинхронных форматов, таких как [Lottie](/docs/cli/reference/formats/lottie-files); настройки проверки проекта определяют, требуется ли также утверждение готовых переводов.
## `requiresReview` [#requires-review]
**Тип** `boolean` · **Необязательно** · **По умолчанию** `false`
Значение по умолчанию для проверки на уровне проекта: если `true`, переведённые артефакты требуют утверждения, прежде чем клиент сможет их использовать. Это должно быть значение `boolean` — для переопределений по glob-шаблонам используйте ключ [`files..requiresReview`](#files) для отдельных файлов (он принимает `boolean` или globs `{ include, exclude }`). Политика для отдельного файла имеет приоритет; файлы, не соответствующие ни glob-шаблону `include`, ни `exclude`, используют это значение верхнего уровня по умолчанию.
```json title="gt.config.json"
{
"requiresReview": true
}
```
## `src` [#src]
**Тип** `string[]` · **Необязательно** · **По умолчанию** glob-шаблоны исходных файлов, зависящие от фреймворка
Массив glob-шаблонов для исходных файлов, которые сканируются на наличие встроенного контента. В проектах семейства React по умолчанию сканируются файлы JavaScript и TypeScript в каталогах `src`, `app`, `pages` и `components`. В проектах Vue дополнительно сканируются файлы `*.vue` в корне, а также файлы JavaScript, TypeScript и Vue в стандартных каталогах Vue и Nuxt, таких как `composables`, `layouts`, `plugins`, `server`, `stores`, `utils` и `views`.
```json title="gt.config.json"
{
"src": [
"src/**/*.{js,jsx,ts,tsx}",
"app/**/*.{js,jsx,ts,tsx}",
"pages/**/*.{js,jsx,ts,tsx}",
"components/**/*.{js,jsx,ts,tsx}"
]
}
```
## `dictionary` [#dictionary]
**Тип** `string` · **Необязательный** · **По умолчанию** —
Относительный путь к файлу словаря. Если параметр не указан, CLI ищет `dictionary.[json|ts|js]` в `./src` и `./`.
```json title="gt.config.json"
{
"dictionary": "./dictionary.json"
}
```
## `branchOptions` [#branch-options]
**Тип** `object` · **Необязательно** · **По умолчанию** —
Настраивает отслеживание переводов по веткам. См. [Отслеживание переводов по веткам](/docs/cli/guides/branching). Флаги CLI имеют приоритет над этими значениями.
| Свойство | Описание | Тип | Необязательно | По умолчанию |
| -------------------- | -------------------------------------------------------------- | --------- | ------------- | ------------ |
| `enabled` | Включает ветвление для проекта. | `boolean` | Да | `false` |
| `currentBranch` | Переопределяет обнаруженное имя ветки. | `string` | Да | — |
| `autoDetectBranches` | Определяет связи между входящими и текущими ветками. | `boolean` | Да | `true` |
| `remoteName` | Удалённый репозиторий Git, используемый для определения ветки. | `string` | Да | `origin` |
```json title="gt.config.json"
{
"branchOptions": {
"enabled": true,
"currentBranch": "my-feature-branch",
"autoDetectBranches": true,
"remoteName": "origin"
}
}
```
## `customMapping` [#custom-mapping]
**Тип** `object` · **Необязательно** · **По умолчанию** —
Задает для локали алиас с другим кодом и при необходимости переопределяет её свойства. Например, задайте алиас `cn` для официального кода `zh`.
При использовании алиаса указывайте в `defaultLocale` и в элементах `locales` имя алиаса (`cn`), а не каноническое имя (`zh`).
```json title="gt.config.json"
{
"defaultLocale": "cn",
"locales": ["cn", "fr", "en"],
"customMapping": {
"cn": {
"code": "zh",
"name": "Mandarin"
}
}
}
```
## `options.saveLocal` [#save-local]
**Type** `boolean` · **Optional** · **Default** `false`
Обнаруживает правки в ранее скачанных локальных файлах перевода и отправляет их diff'ы до того, как [`gt translate`](/docs/cli/reference/commands/translate) или [`gt stage`](/docs/cli/reference/commands/stage) поставят в очередь новые задачи. Задавайте этот параметр в корневом объекте `options`. Флаги `--save-local` и `--no-save-local` переопределяют эту настройку для одного запуска.
```json title="gt.config.json"
{
"options": {
"saveLocal": true
}
}
```
### История версий
| Версия | Изменения |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `2.20.3` | Локальные правки стали опциональными: задайте этому ключу значение `true` или передайте `--save-local`, чтобы включить этот шаг. |
## Публикация в CDN [#cdn-publishing]
По умолчанию CLI не публикует в CDN. Когда CDN включён в настройках проекта, вы можете управлять публикацией глобально, для отдельных файлов или для отдельных команд.
* **Глобально:** установите [`publish`](#publish) верхнего уровня в `true` или передайте `--publish` в [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload) или [`save-local`](/docs/cli/reference/commands/save-local).
* **Только для файлов GT:** установите `publish: true` в `files.gt`.
* **Для каждого файла:** в массиве `include` замените glob-строку на объект с `pattern` и `publish`, чтобы явно включать или исключать совпавшие файлы.
```json title="gt.config.json"
{
"files": {
"json": {
"include": [
{ "pattern": "locales/[locale]/*.json", "publish": true },
{ "pattern": "locales/[locale]/internal/**/*.json", "publish": false }
]
}
}
}
```
Для любого файла CLI определяет публикацию в следующем порядке: явное исключение через `"publish": false`, затем явное включение через `"publish": true`, затем глобальная настройка `publish`. Если настройка публикации отсутствует на всех уровнях, шаг публикации пропускается.
## Locadex preserve local edits [#locadex-requirements]
Если в автоматизации Locadex включена опция **Preserve local edits**, задайте либо `"publish": true` на верхнем уровне, либо `files.gt.output`. Locadex проверяет это перед запуском перевода.
```json title="gt.config.json"
{
"files": {
"gt": {
"output": "public/i18n/[locale].json"
}
}
}
```
Настройки отдельных файлов и `files.gt.publish` эту проверку не проходят. Если публикация на CDN не включена на верхнем уровне, параметр `files.gt.output` указывает workflow, где хранятся локальные GTJSON-переводы, чтобы тот мог сохранить правки.
## Пример конфигурации [#example]
```json title="gt.config.json"
{
"$schema": "https://assets.gtx.dev/config-schema.json",
"defaultLocale": "en",
"locales": ["fr", "es"],
"files": {
"gt": {
"output": "public/i18n/[locale].json"
},
"mdx": {
"include": ["content/docs/[locale]/**/*.mdx"],
"transform": "*.[locale].mdx"
},
"json": {
"include": ["resources/[locale]/**/*.json"],
"exclude": ["resources/[locale]/exclude/**/*.json"]
}
}
}
```
Один запуск [`gt translate`](/docs/cli/reference/commands/translate) с этой конфигурацией переводит MDX-файлы в каталоге `content/docs/en` (с сохранением в `content/docs/fr` и `content/docs/es` с расширениями `.fr.mdx` и `.es.mdx`), JSON-файлы в каталоге `resources/en` (кроме `resources/en/exclude`), а также все встроенные компоненты [``](/docs/react/reference/components/t) и записи словаря. Переводы GT сохраняются в `public/i18n/fr.json` и `public/i18n/es.json`.
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.