# gt: General Translation CLI tool: Configuration
URL: https://generaltranslation.com/en-US/docs/cli/reference/config.mdx
---

title: Configuration
description: Configure the General Translation CLI with the gt.config.json file. API reference for gt.config.json.

---

The `gt.config.json` file configures what the CLI translates and where results are saved. Place it at the root of your project. Create it with [`gt init`](/docs/cli/reference/commands/init) or [`gt configure`](/docs/cli/reference/commands/configure), or write it by hand.

*Note: Add the [JSON Schema](https://assets.gtx.dev/config-schema.json) with a `$schema` key for editor validation and autocompletion.*

## Options [#options]

| Option | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`defaultLocale`](#default-locale) | Locale your source content is written in. | `string` | Yes | `en` |
| [`locales`](#locales) | Target locales to translate into. | `string[]` | Yes | — |
| [`files`](#files) | Which files to translate and where to save them. | `object` | Yes | — |
| [`publish`](#publish) | Publish translated files to the CDN. | `boolean` | Yes | `false` |
| [`stageTranslations`](#stage) | Require human review before translations are served. | `boolean` | Yes | `false` |
| [`requiresReview`](#requires-review) | Default review-gating policy for all translated files. | `boolean` | Yes | `false` |
| [`src`](#src) | Glob patterns for source files scanned for inline content. | `string[]` | Yes | See [`src`](#src) |
| [`dictionary`](#dictionary) | Path to a dictionary file. | `string` | Yes | — |
| [`branchOptions`](#branch-options) | Branch-based translation tracking settings. | `object` | Yes | — |
| [`customMapping`](#custom-mapping) | Locale aliases and property overrides. | `object` | Yes | — |

## `defaultLocale` [#default-locale]

**Type** `string` · **Optional** · **Default** `en`

The locale your source content is written in. This is the locale the CLI translates from, and the fallback locale when you use `gt-next` or `gt-react`.

```json title="gt.config.json"
{
  "defaultLocale": "en"
}
```

## `locales` [#locales]

**Type** `string[]` · **Optional** · **Default** —

The target locales to translate into. See [supported locales](/docs/platform/dashboard/reference/supported-locales) for accepted codes. When you use `gt-next` or `gt-react`, these are also the locales your app supports.

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

## `files` [#files]

**Type** `object` · **Optional** · **Default** —

An object with one key per file type to translate. Each type maps to an object of settings. See [File formats](/docs/cli/reference/formats/gt-jsx-files) for per-type guidance.

### Supported file types

| Key | File type | Reference |
| --- | --- | --- |
| `gt` | General Translation files for `gt-next`, `gt-react`, and `gt-react-native`. | [GT](/docs/cli/reference/formats/gt-jsx-files) |
| `json` | JSON files. | [JSON](/docs/cli/reference/formats/json-files) |
| `yaml` | YAML files (`.yaml` and `.yml`). | [YAML](/docs/cli/reference/formats/yaml-files) |
| `pot` | PO/POT gettext files. | [PO / POT](/docs/cli/reference/formats/po-pot-files) |
| `mdx` | MDX files. | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `md` | Markdown files. | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `ts` | TypeScript files. | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `js` | JavaScript files. | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `html` | HTML files. | [HTML](/docs/cli/reference/formats/html-files) |
| `txt` | Plain text files. | [Plain text](/docs/cli/reference/formats/plain-text-files) |
| `twilioContentJson` | Twilio Content JSON templates. | — |

### File type keys

Each file type accepts the following keys.

- `include` — an array of glob patterns matching files to translate. Use the `[locale]` placeholder: the CLI replaces it with `defaultLocale` to find source files, and with each target code to save translations. Required for every type except `gt`.
- `exclude` — an array of glob patterns to skip. The `[locale]` placeholder is optional here; use `[locales]` to exclude a path across all locales.
- `transform` — remaps output file names. A string with a `*` wildcard remaps the extension (for example `*.[locale].json`). An object with `match` and `replace` supports regex capture groups and the `{locale}` placeholder.
- `transformationFormat` — outputs translated files in a different format than the source. For example, `pot` sources with `"transformationFormat": "PO"` produce `.po` files.
- `requiresReview` — gates translated files behind human review. Accepts `true`/`false`, or an object with `include` and `exclude` glob arrays where `exclude` takes precedence.
- `output` — for `gt` files only, the local save path with a `[locale]` placeholder, such as `public/i18n/[locale].json`.
- `parsingFlags` — for `gt` files only, flags that control inline content parsing. See [`autoderive`](/docs/cli/guides/using-autoderive) and [automatic JSX injection](/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"]
    }
  }
}
```

## `publish` [#publish]

**Type** `boolean` · **Optional** · **Default** `false`

When `true`, translated files are published to the General Translation CDN after [`translate`](/docs/cli/reference/commands/translate), `upload`, or `save-local`. See [CDN publishing](#cdn-publishing) for per-file and per-command control.

```json title="gt.config.json"
{
  "publish": true
}
```

## `stageTranslations` [#stage]

**Type** `boolean` · **Optional** · **Default** `false`

When `true`, translations require human review before they are served. The CLI sets this automatically the first time you run [`gt stage`](/docs/cli/reference/commands/stage). Once enabled, `translate` only downloads translations for versions you have staged with `gt stage`; if nothing has been staged, there is nothing to download.

## `requiresReview` [#requires-review]

**Type** `boolean` · **Optional** · **Default** `false`

The project-wide default for review gating: when `true`, translated artifacts require approval before the client uses them. This must be a boolean — use the per-file [`files.<type>.requiresReview`](#files) key (which accepts a boolean or `{ include, exclude }` globs) for glob-scoped overrides. A per-file policy takes precedence; files matching neither an `include` nor `exclude` glob fall back to this top-level default.

```json title="gt.config.json"
{
  "requiresReview": true
}
```

## `src` [#src]

**Type** `string[]` · **Optional** · **Default** `src`, `app`, `pages`, `components` globs

An array of glob patterns for the source files scanned for inline content when you use `gt-next`, `gt-react`, or `gt-react-native`.

```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]

**Type** `string` · **Optional** · **Default** —

The relative path to a dictionary file. When omitted, the CLI looks for `dictionary.[json|ts|js]` in `./src` and `./`.

```json title="gt.config.json"
{
  "dictionary": "./dictionary.json"
}
```

## `branchOptions` [#branch-options]

**Type** `object` · **Optional** · **Default** —

Configures branch-based translation tracking. See [Tracking translations by branch](/docs/cli/guides/branching). CLI flags take precedence over these values.

| Property | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `enabled` | Enable branching for the Project. | `boolean` | Yes | `false` |
| `currentBranch` | Override the detected branch name. | `string` | Yes | — |
| `autoDetectBranches` | Detect incoming and checked-out branch relationships. | `boolean` | Yes | `true` |
| `remoteName` | Git remote used for branch detection. | `string` | Yes | `origin` |

```json title="gt.config.json"
{
  "branchOptions": {
    "enabled": true,
    "currentBranch": "my-feature-branch",
    "autoDetectBranches": true,
    "remoteName": "origin"
  }
}
```

## `customMapping` [#custom-mapping]

**Type** `object` · **Optional** · **Default** —

Aliases a locale to a different code, and optionally overrides its properties. For example, alias `cn` to the official code `zh`.

```json title="gt.config.json"
{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarin"
    }
  }
}
```

## CDN publishing [#cdn-publishing]

By default the CLI does not publish to the CDN. When the CDN is enabled in your Project settings, you can control publishing globally, per file, or per command.

- **Global:** set top-level [`publish`](#publish) to `true`, or pass `--publish` to `translate`, `upload`, or `save-local`.
- **GT files only:** set `publish: true` under `files.gt`.
- **Per file:** in an `include` array, replace a glob string with an object of `pattern` and `publish` to opt matched files in or out.

```json title="gt.config.json"
{
  "files": {
    "json": {
      "include": [
        { "pattern": "locales/[locale]/*.json", "publish": true },
        { "pattern": "locales/[locale]/internal/**/*.json", "publish": false }
      ]
    }
  }
}
```

For any file, the CLI resolves publishing in this order: an explicit `"publish": false` opt-out, then an explicit `"publish": true` opt-in, then the global `publish` setting. If no publish configuration exists at any level, the publish step is skipped.

## Example configuration [#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"]
    }
  }
}
```

A single [`gt translate`](/docs/cli/reference/commands/translate) run with this config translates the MDX files under `content/docs/en` (saved to `content/docs/fr` and `content/docs/es` as `.fr.mdx` and `.es.mdx`), the JSON files under `resources/en` (excluding `resources/en/exclude`), and any inline [`<T>`](/docs/react/reference/components/t) components and dictionary entries. GT translations are saved to `public/i18n/fr.json` and `public/i18n/es.json`.