# 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. The published schema does not yet include the `lottie` and `fonts` keys added in `gt` 2.16.0, so editors may flag those valid settings until the schema is refreshed.*

## 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 | — |
| [`fonts`](#fonts) | Font files to make available to Lottie translation jobs. | `object` | Yes | — |
| [`publish`](#publish) | Publish translated files to the CDN. | `boolean` | Yes | `false` |
| [`stageTranslations`](#stage) | Use the staged workflow before downloading translations. | `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. | — |
| `lottie` | dotLottie animation files (`.lottie`). | [Lottie](/docs/cli/reference/formats/lottie-files) |

### 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 placeholders in [Locale placeholders](#locale-placeholders).
- `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"]
    }
  }
}
```

### Locale placeholders [#locale-placeholders]

The `replace` value of an object `transform` accepts `{...}` placeholders that expand to properties of the target locale. Unrecognized names are left in the output as literal text.

| Placeholder | Description | Example for `pt-BR` |
| --- | --- | --- |
| `{locale}` | The locale exactly as written in [`locales`](#locales). `{localeCode}` is an alias. | `pt-BR` |
| `{localeName}` | English name of the locale, including its region. | `Brazilian Portuguese` |
| `{localeNativeName}` | Native name of the locale, including its region. | `português (Brasil)` |
| `{languageCode}` | Language subtag on its own. | `pt` |
| `{regionCode}` | Region subtag on its own. | `BR` |
| `{scriptCode}` | Script subtag on its own. | `Latn` |
| `{minimizedCode}` | Shortest unambiguous form of the tag. | `pt` |
| `{maximizedCode}` | Fully expanded tag, including script. | `pt-Latn-BR` |
| `{emoji}` | Flag emoji associated with the locale. | 🇧🇷 |

The remaining [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) fields are also accepted by name, including `languageName`, `nativeLanguageName`, `regionName`, `nativeRegionName`, `scriptName`, `nativeScriptName`, `nameWithRegionCode`, `nativeNameWithRegionCode`, `maximizedName`, `nativeMaximizedName`, `minimizedName`, and `nativeMinimizedName`.

`{locale}` uses the spelling from your configuration rather than the canonical BCP-47 form, so a locale configured as `fr-ca` produces `fr-ca` and not `fr-CA`. This matches the `[locale]` placeholder in `include`, `exclude`, and `output`, so file paths and localized URLs agree. Use `{minimizedCode}`, `{maximizedCode}`, or `{regionCode}` when you need a normalized tag instead.

```json title="gt.config.json"
{
  "files": {
    "json": {
      "include": ["locales/[locale]/**/*.json"],
      "transform": {
        "match": "locales/(.*)/(.*)\\.json",
        "replace": "locales/{locale}/$2.{languageCode}.json"
      }
    }
  }
}
```

## `fonts` [#fonts]

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

Font files to upload before translation jobs run. Use `include` and optional `exclude` globs that resolve from the project root. Match `.ttf` and `.otf` files; the CLI reads them as binary data and uploads them as persistent Organization assets for Lottie layout processing.

| Property | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `include` | Glob patterns for fonts to upload. | `string[]` | No | — |
| `exclude` | Glob patterns to omit from the matches. | `string[]` | Yes | `[]` |

```json title="gt.config.json"
{
  "fonts": {
    "include": ["public/fonts/**/*.{ttf,otf}"],
    "exclude": ["public/fonts/legacy/**"]
  }
}
```

The CLI syncs matching fonts before [`gt stage`](/docs/cli/reference/commands/stage), [`gt upload`](/docs/cli/reference/commands/upload), [`gt enqueue`](/docs/cli/reference/commands/enqueue), and [`gt translate`](/docs/cli/reference/commands/translate) runs that enqueue new work. When `stageTranslations` is enabled, [`gt translate`](/docs/cli/reference/commands/translate) only downloads the staged version and does not sync fonts. A failed font sync emits a warning but does not stop translation; Lottie processing continues with fallback fonts. See [Upload Project assets](/docs/platform/openapi/reference/project/upload-assets) for font validation and storage behavior.

## `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`](/docs/cli/reference/commands/upload), or [`save-local`](/docs/cli/reference/commands/save-local). Lottie translations remain available through API and CLI downloads only; setting `publish` does not make `.lottie` files available from the CDN. 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`, the CLI downloads only versions submitted with [`gt stage`](/docs/cli/reference/commands/stage). The CLI sets this automatically the first time you run [`gt stage`](/docs/cli/reference/commands/stage). Use the staged workflow for human review and for asynchronous formats such as [Lottie](/docs/cli/reference/formats/lottie-files); the Project's review settings determine whether completed translations also require approval.

## `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`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload), or [`save-local`](/docs/cli/reference/commands/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`.