# gt: General Translation CLI tool: Конфигурация URL: https://generaltranslation.com/ru/docs/cli/reference/config.mdx --- title: Конфигурация description: Документация по файлу конфигурации gt.config.json --- ## Обзор Файл `gt.config.json` используется для настройки параметров GT проекта. Его следует разместить в корневом каталоге проекта. Мастер настройки CLI [`npx gt init`](/docs/cli/init) создаст файл `gt.config.json` за вас. ## Конфигурация Файл `gt.config.json` поддерживает следующие свойства, но не ограничивается ими: * `defaultLocale`: Локаль по умолчанию для вашего проекта. Это локаль, на которой написан исходный контент. Она также используется как резервная локаль проекта (если вы используете `gt-next` или `gt-react`). * `locales`: Массив локалей проекта. Это локали, на которые вы хотите перевести проект. Подробнее см. в разделе [поддерживаемые локали](/docs/platform/supported-locales). Если вы используете `gt-next` или `gt-react`, это также локали, которые поддерживает ваше приложение. * `files`: Объект, содержащий информацию о контенте, который вы хотите перевести. * `publish`: Необязательный логический флаг. Если задано значение `true`, переведённые файлы публикуются в CDN GT после выполнения `translate`, `upload` или `save-local`. Значение по умолчанию — `false` (без публикации). Его также можно задать для отдельной команды с помощью `--publish`. Подробнее см. в разделе [публикация в CDN](#cdn-publishing). * `stageTranslations`: Необязательный логический флаг, который указывает, настроен ли проект на ручную проверку переводов. * `src`: Необязательный массив glob-шаблонов для исходных файлов. По умолчанию имеет значение: ```json [ "src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}", "components/**/*.{js,jsx,ts,tsx}" ] ``` * `dictionary`: Необязательная строка, указывающая относительный путь к файлу словаря. * `branchOptions`: Необязательный объект для настройки отслеживания переводов по веткам. Подробнее см. в разделе [branching](/docs/cli/branching). Чтобы упростить проверку файла `gt.config.json`, можно использовать [JSON Schema](https://assets.gtx.dev/config-schema.json) для CLI. Добавьте её в начало файла `gt.config.json`: ```json title="gt.config.json" copy { "$schema": "https://assets.gtx.dev/config-schema.json" } ``` Ниже приведён шаблон файла `gt.config.json`: ```json title="gt.config.json" { "$schema": "https://assets.gtx.dev/config-schema.json", "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "..." }, "json": { "include": [...] }, "mdx": { "include": [...] }, "md": { "include": [...] } }, "src": [ "src/**/*.{ts,tsx}", ], "dictionary": "./dictionary.json" } ``` ### Алиас локали Если вы хотите задать алиас локали (например, `cn` вместо `zh`), укажите пользовательское сопоставление в файле `gt.config.json`. ```json title="gt.config.json" { "customMapping": { // Локаль-алиас "cn": { "code": "zh" // Официальный код локали BCP 47 } } } ``` Вы также можете указать разные атрибуты для локали, заданной через псевдоним. ```json title="gt.config.json" { "customMapping": { "cn": { "code": "zh", "name": "Mandarin" } } } ``` ### Параметры веток Если вы хотите настроить параметры веток в файле конфигурации, используйте объект `branchOptions`: ```json title="gt.config.json" { "branchOptions": { "enabled": true, "currentBranch": "my-feature-branch", "autoDetectBranches": true, "remoteName": "origin" } } ``` | Свойство | Описание | По умолчанию | | -------------------- | ----------------------------------------------------------------------- | ------------ | | `enabled` | Включает ветвление для проекта | `false` | | `currentBranch` | Задаёт имя текущей ветки вручную (вместо автоопределения) | `undefined` | | `autoDetectBranches` | Автоматически определяет связи между ветками (входящие и текущие ветки) | `true` | | `remoteName` | Имя удалённого репозитория Git, используемое для определения веток | `"origin"` | Флаги CLI имеют приоритет над параметрами в файле конфигурации. Подробнее см. в [руководстве по ветвлению](/docs/cli/branching). *** ## `files` ### Поддерживаемые типы файлов `files` должен содержать ключ для каждого типа файлов, который вы хотите переводить. Вы можете настроить проект так, чтобы использовать разные типы файлов одновременно и переводить их все. Сейчас поддерживаются следующие типы файлов: * `gt`: файлы General Translation. Используются в [`gt-next`](/docs/next), [`gt-react`](/docs/react) и [`gt-react-native`](/docs/react-native). * `json`: файлы JSON. * `pot`: файлы PO/POT (gettext). * `yaml`: файлы YAML. * `mdx`: файлы компонентов Markdown (MDX). * `md`: файлы Markdown (MD). * `js`: файлы JavaScript. * `ts`: файлы TypeScript. * `html`: файлы HTML. * `txt`: текстовые файлы. * `twilioContentJson`: файлы Twilio Content JSON. Используются для перевода [Twilio Content Templates](https://www.twilio.com/docs/content). Каждому типу файлов должен соответствовать объект, содержащий один или несколько из следующих ключей: * `include` * `exclude` * `transform` * `transformationFormat` * `output` ### `include` Если ключ `include` используется, его значение должно быть массивом glob-шаблонов, соответствующих файлам, которые нужно перевести. Обязательно используйте заполнитель `[locale]` в glob-шаблонах, чтобы исходные файлы находились корректно, а переведённые файлы сохранялись в нужное место. При поиске файлов для перевода CLI-инструмент заменяет заполнитель `[locale]` значением `defaultLocale`. CLI-инструмент сохранит переведённые файлы по соответствующему пути, заменив заполнитель `[locale]` целевым кодом локали. ```json { "include": ["docs/[locale]/**/*.json"] } ``` ### `exclude` Если используется ключ `exclude`, его значением должен быть массив glob-шаблонов, соответствующих файлам, которые нужно исключить из перевода. Шаблон такой же, как и для `include`, за исключением того, что заполнитель `[locale]` здесь необязателен. Если он указан, вместо него будет подставлено значение `defaultLocale`. ```json { "exclude": ["docs/[locale]/exclude/**/*.json"] } ``` Если вы хотите исключить файлы из перевода для всех локалей, используйте заполнитель `[locales]` вместо `[locale]`. ```json { "exclude": ["docs/[locales]/exclude/**/*.json"] } ``` ### `transform` `transform` может быть строкой или объектом. Если `transform` — это строка, она задаёт переименование имени файла. Она должна содержать подстановочный знак `*`, который будет заменён исходным именем файла (всем, что находится до первой `.`). Например, если вы хотите, чтобы у всех переведённых файлов расширение было `.[locale].json` вместо `.json`, можно использовать следующую конфигурацию: ```json { "transform": "*.[locale].json" } ``` В качестве альтернативы, если `transform` — это объект, он должен содержать следующие свойства: * `match` (необязательно): регулярное выражение для поиска строк, поддерживает группы захвата * `replace` (обязательно): строка или регулярное выражение для замены совпадения Оба значения поддерживают группы захвата регулярных выражений и применяются к полному относительному имени выходного файла. ```json { "transform": { "match": "^(.*)$", "replace": "{locale}/$1" } } ``` Например, при такой конфигурации переведённые файлы будут сохраняться в подкаталоге целевой локали. #### Специальные заполнители Параметр `transform` поддерживает несколько специальных заполнителей, которые можно использовать как в строках `match`, так и в строках `replace`: * `{locale}`: заполнитель кода локали, который ведет себя по-разному в зависимости от контекста: * **В строках `match`**: заменяется кодом локали по умолчанию (например, `"en"`), чтобы помочь определить исходные файлы * **В строках `replace`**: заменяется кодом целевой локали (например, `"fr"`, `"es"`) для выходных файлов перевода Например, если локаль по умолчанию — `"en"`, а перевод выполняется на `"fr"`: * Шаблон `match` `"content/{locale}/file.md"` превращается в `"content/en/file.md"` * Шаблон `replace` `"content/{locale}/file.md"` превращается в `"content/fr/file.md"` Кроме того, любое другое свойство из `getLocaleProperties` можно использовать как заполнитель с тем же контекстно-зависимым поведением. Это полезно, если для переведенных файлов в вашей документации или i18n-фреймворке требуется определенное расширение файла вместо маршрутизации по локалям на основе подкаталогов. ### `transformationFormat` Ключ `transformationFormat` задаёт другой формат файла для выходных файлов перевода. Это полезно, когда ваши исходные файлы представляют собой шаблоны и после перевода должны превращаться в файлы другого типа. Например, файлы POT (PO Template) являются исходными шаблонами, но результатом перевода должны быть файлы PO: ```json { "files": { "pot": { "include": ["locales/[locale]/**/*.pot"], "transformationFormat": "PO" } } } ``` Значение должно быть строкой, соответствующей одному из ключей поддерживаемых форматов файлов (например, `"PO"`). ### `output` Этот ключ используется только для файлов General Translation — в частности, для локального сохранения переводов. Если вы используете GT CDN, этот ключ не требуется. Значение должно быть строкой, содержащей заполнитель `[locale]`, который указывает путь, по которому будут сохранены переводы. Например, если вы хотите сохранить испанские переводы в файл `ui.es.json` в каталоге `public/i18n`, используйте следующую строку: ```json { "output": "public/i18n/[locale].json" } ``` Этот параметр следует использовать только если вы используете `gt-next` или `gt-react` и хотите сохранять переводы локально, а не через GT CDN. Сейчас для каждой локали можно сгенерировать только один файл. *** ### Тип файла: `gt` [#gt] **Поддерживаемые ключи** * `output` (обязательно) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "public/i18n/[locale].json" } } } ``` Эта конфигурация укажет CLI-инструменту сохранять французские и испанские переводы в каталоге `public/i18n/[locale].json`. По умолчанию при такой конфигурации CLI-инструмент не будет публиковать ваши переводы в CDN GT. *** ### Тип файла: `json` [#json] **Поддерживаемые ключи** * `include` (обязательный) * `exclude` (необязательный) * `transform` (необязательный) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "json": { "include": ["json_files/[locale]/**/*.json"], "exclude": ["json_files/[locale]/exclude/**/*.json"] } } } ``` Допустим, локаль проекта по умолчанию — `en`, и вы хотите перевести проект на `fr` и `es`. С этой конфигурацией CLI-инструмент будет искать все JSON-файлы в подкаталоге `json_files/en/` и сохранять переведённые файлы в `json_files/fr/` и `json_files/es/`. Файлы из подкаталога `json_files/en/exclude/` будут игнорироваться. *** ### Тип файла: `yaml` [#yaml] **Поддерживаемые ключи** * `include` (обязательный) * `exclude` (необязательный) * `transform` (необязательный) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "yaml": { "include": ["yaml_files/[locale]/**/*.yaml"], "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"] } } } ``` Допустим, локаль проекта по умолчанию — `en`, и вы хотите перевести его на `fr` и `es`. С этой конфигурацией CLI-инструмент будет искать все YAML-файлы в подкаталоге `yaml_files/en/` и сохранять переведённые файлы в `yaml_files/fr/` и `yaml_files/es/`. Все файлы в подкаталоге `yaml_files/en/exclude/` будут проигнорированы. *** ### Тип файла: `mdx` [#mdx] **Поддерживаемые ключи** * `include` (обязательно) * `exclude` (необязательно) * `transform` (необязательно) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "mdx": { "include": ["content/docs/[locale]/**/*.mdx"], "transform": "*.[locale].mdx" } } } ``` Эта конфигурация укажет CLI-инструменту искать все MDX-файлы в каталоге `content/docs/en` и сохранять переведённые файлы в каталог `content/docs/ja`. Ключ `transform` меняет расширение переведённых файлов на `.ja.mdx`. *** ### Тип файла: `md` [#md] **Поддерживаемые ключи** * `include` (обязательный) * `exclude` (необязательный) * `transform` (необязательный) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "md": { "include": ["content/docs/[locale]/**/*.md"], "exclude": ["content/docs/[locale]/exclude/**/*.md"], "transform": "*.[locale].md" } } } ``` Эта конфигурация укажет CLI-инструменту искать все MD-файлы в каталоге `content/docs/en` и сохранять переведенные файлы в каталог `content/docs/ja`. Ключ `transform` изменяет расширение переведенных файлов на `.ja.md`. Все файлы в каталоге `content/docs/en/exclude` будут игнорироваться. *** ### Тип файла: `js` [#js] **Поддерживаемые ключи** * `include` (обязательный) * `exclude` (необязательный) * `transform` (необязательный) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "js": { "include": ["scripts/[locale]/**/*.js"] } } } ``` Эта конфигурация укажет CLI-инструменту искать все JavaScript-файлы в каталоге `scripts/en` и сохранять переведённые файлы в каталоги `scripts/fr` и `scripts/es`. *** ### Тип файла: `ts` [#ts] **Поддерживаемые ключи** * `include` (обязательно) * `exclude` (необязательно) * `transform` (необязательно) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "ts": { "include": ["scripts/[locale]/**/*.ts"] } } } ``` Эта конфигурация укажет CLI-инструменту искать все файлы TypeScript в каталоге `scripts/en` и сохранять переведённые файлы в каталоги `scripts/fr` и `scripts/es`. *** ### Тип файла: `html` [#html] **Поддерживаемые ключи** * `include` (обязательно) * `exclude` (необязательно) * `transform` (необязательно) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "html": { "include": ["content/docs/[locale]/**/*.html"], "exclude": ["content/docs/[locale]/exclude/**/*.html"], "transform": "*.[locale].html" } } } ``` Эта конфигурация укажет CLI-инструменту искать все HTML-файлы в каталоге `content/docs/en` и сохранять переведённые файлы в каталог `content/docs/ja`. Ключ `transform` изменяет расширение переведённых файлов на `.ja.html`. Все файлы в каталоге `content/docs/en/exclude` будут игнорироваться. *** ### Тип файла: `txt` [#txt] **Поддерживаемые ключи** * `include` (обязательный) * `exclude` (необязательный) * `transform` (необязательный) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "txt": { "include": ["content/docs/[locale]/**/*.txt"], "exclude": ["content/docs/[locale]/exclude/**/*.txt"], "transform": "*.[locale].txt" } } } ``` Эта конфигурация укажет CLI-инструменту искать все текстовые файлы в каталоге `content/docs/en` и сохранять переведённые файлы в каталог `content/docs/ja`. Ключ `transform` изменяет расширение переведённых файлов на `.ja.txt`. Все файлы в каталоге `content/docs/en/exclude` будут проигнорированы. *** ### Тип файла: `twilioContentJson` [#twilioContentJson] **Поддерживаемые ключи** * `include` (обязательный) * `exclude` (необязательный) * `transform` (необязательный) **Пример** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "twilioContentJson": { "include": ["twilio/[locale]/**/*.json"] } } } ``` Эта конфигурация укажет CLI-инструменту искать все файлы Twilio Content JSON в каталоге `twilio/en` и сохранять переведённые файлы в каталоги `twilio/es` и `twilio/fr`. Файлы Twilio Content JSON — это структурированные шаблоны, используемые в [Twilio's Content Template Builder](https://www.twilio.com/docs/content) для сообщений в WhatsApp, SMS и RCS. CLI-инструмент переводит текстовые значения, отображаемые пользователю (текст сообщения, подписи кнопок, заголовки карточек), сохраняя при этом структуру шаблона, заполнители переменных и непереводимые поля. *** ## Публикация в CDN [#cdn-publishing] По умолчанию CLI не публикует переведённые файлы в CDN GT. Если вы включили CDN в настройках проекта, вы можете управлять публикацией глобально, для отдельных файлов или отдельных команд. ### Глобальный флаг публикации Установите `publish` на верхнем уровне, чтобы опубликовать **все** переведённые файлы в CDN: ```json title="gt.config.json" { "publish": true } ``` Вы также можете передать флаг `--publish` командам `translate`, `upload` или `save-local`: ```bash npx gt translate --publish ``` ### Флаг `publish` для GT JSON Чтобы публиковать только внутренний формат переводов GT, используйте ключ `publish` в `files.gt`: ```json title="gt.config.json" { "files": { "gt": { "output": "public/i18n/[locale].json", "publish": true } } } ``` ### Управление публикацией на уровне отдельных файлов Для других типов файлов (`json`, `yaml`, `mdx`, `md`, `po`, `xliff`, `csv`, `properties`) можно управлять публикацией для каждого файла, используя объект в массиве `include` вместо обычной glob-строки: ```json title="gt.config.json" { "files": { "json": { "include": [ { "pattern": "locales/[locale]/*.json", "publish": true }, { "pattern": "locales/[locale]/internal/**/*.json", "publish": false } ] } } } ``` Каждая запись в `include` может быть одного из двух типов: * **Строка** — glob-шаблон (без явного указания публикации; используется глобальная настройка `publish`) * **Объект** с `pattern` (glob) и `publish` (boolean) — явно включает или исключает совпавшие файлы ### Порядок определения Для любого файла CLI определяет, нужно ли его публиковать, в следующем порядке: 1. **Явный отказ** — файл соответствует записи в `include` с `"publish": false` → не публикуется или удаляется из CDN 2. **Явное разрешение** — файл соответствует записи в `include` с `"publish": true` → публикуется в CDN 3. **Глобальное значение по умолчанию** — используется настройка `publish` верхнего уровня (по умолчанию `false`, если не задана) Если конфигурация публикации отсутствует на всех уровнях, шаг публикации полностью пропускается. *** ## Пример конфигурации Разберём на примере файл `gt.config.json`: ```json title="gt.config.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/translate) переводятся следующие файлы: * Все MDX-файлы в каталоге `content/docs/en`. * Все JSON-файлы в каталоге `resources/en` (кроме файлов в каталоге `resources/en/exclude`). * Все встроенные компоненты `` в вашем проекте React или Next.js. * Файл `dictionary.[json|js|ts]`. GT: Переводы будут сохранены в `public/i18n/es.json` и `public/i18n/fr.json`. Эти файлы можно загружать с помощью [`loadTranslations`](/docs/react/api/config/load-translations). MDX: Переводы будут сохранены в каталогах `content/docs/fr` и `content/docs/es`. Расширения файлов будут изменены на `.fr.mdx` и `.es.mdx` соответственно (вместо `.mdx`). JSON: Переводы будут сохранены в каталогах `resources/fr` и `resources/es`. *** ## Что дальше Узнайте, как использовать [команду init](/docs/cli/init), чтобы создать этот файл конфигурации.