# gt: General Translation CLI tool: Configuration
URL: https://generaltranslation.com/en-GB/docs/cli/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
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 the 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 lags behind some valid file keys, including `pot`, `html`, `txt`, `twilioContentJson`, `lottie`, `dotStrings`, `dotStringsdict`, `androidStrings`, `xcstrings`, and `srt`, and also omits `fonts` and `options.saveLocal`. Editors may flag unsupported schema fields until the schema is refreshed.*

## Options [#options]

| Option                               | Description                                                | Type       | Optional | Default               |
| ------------------------------------ | ---------------------------------------------------------- | ---------- | -------- | --------------------- |
| [`projectId`](#project-id)           | project used for API and translation workflows.            | `string`   | Yes      | `GT_PROJECT_ID`       |
| [`baseUrl`](#base-url)               | Base URL for General Translation API requests.             | `string`   | Yes      | `https://api.gtx.dev` |
| [`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      | Framework-specific    |
| [`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      | —                     |
| [`options.saveLocal`](#save-local)   | Detect and submit local translation edits before queueing. | `boolean`  | Yes      | `false`               |

## `projectId` [#project-id]

**Type** `string` · **Optional** · **Default** `GT_PROJECT_ID`

The project used for API and translation workflows. A `--project-id` flag overrides the environment value, but it must match `projectId` when the config includes one.

```json title="gt.config.json"
{
  "projectId": "project-id"
}
```

## `baseUrl` [#base-url]

**Type** `string` · **Optional** · **Default** `https://api.gtx.dev`

The API origin used by CLI requests, including [`gt api`](/docs/cli/reference/commands/api). Set this only when your workflow uses a custom General Translation API endpoint.

```json title="gt.config.json"
{
  "baseUrl": "https://api.gtx.dev"
}
```

## `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`, `gt-react`, or `gt-vue`.

```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. Framework initialisers that accept a locale list also use these as 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 for each file type to translate. Each type maps to a settings object. See [File formats](/docs/cli/reference/formats/gt-jsx-files) for type-specific guidance.

### Supported file types

| Key                 | File type                                                                                                  | Reference                                                                |
| ------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `gt`                | General Translation files for `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start`, and `gt-vue`. | [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)               |
| `srt`               | SubRip subtitle files (`.srt`).                                                                            | [SRT](/docs/cli/reference/formats/srt-files)                             |
| `twilioContentJson` | Twilio Content JSON templates.                                                                             | —                                                                        |
| `lottie`            | dotLottie animation files (`.lottie`).                                                                     | [Lottie](/docs/cli/reference/formats/lottie-files)                       |
| `xcstrings`         | Apple String Catalogues (`.xcstrings`).                                                                    | [.xcstrings](/docs/cli/reference/formats/xcstrings-files)                |
| `dotStrings`        | `.strings` tables, one per locale in a `.lproj` directory.                                                 | [.strings](/docs/cli/reference/formats/dot-strings-files)                |
| `dotStringsdict`    | `.stringsdict` plural files, one per locale in a `.lproj` directory.                                       | [.stringsdict](/docs/cli/reference/formats/dot-stringsdict-files)        |
| `androidStrings`    | Android `strings.xml` resource files.                                                                      | [Android strings.xml](/docs/cli/reference/formats/android-strings-files) |

`dotStrings` and `dotStringsdict` require `gt` 2.18.1 or later, `androidStrings` requires `gt` 2.19.0 or later, `xcstrings` requires `gt` 2.21.0 or later, and `srt` requires `gt` 2.22.2 or later.

<Callout type="info">
  **Changed in v2.18.1:** The Apple file keys changed from `strings` and `stringsdict` to `dotStrings` and `dotStringsdict`. The earlier keys are not recognised in current releases.
</Callout>

### 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 from 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`. This is required when a Locadex workflow uses **Preserve local edits** without top-level CDN publishing; see [Locadex preserve local edits](#locadex-requirements).
* `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. Unrecognised 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` rather than `fr-CA`. This matches the `[locale]` placeholder in `include`, `exclude`, and `output`, ensuring that file paths and localised URLs match. Use `{minimizedCode}`, `{maximizedCode}`, or `{regionCode}` when you need a normalised tag instead.

The one exception is [`androidStrings`](/docs/cli/reference/formats/android-strings-files), where both placeholders expand to an Android resource directory qualifier — `fr-CA` becomes `fr-rCA` — because Android fails the build on a `values-*` directory name it cannot parse.

```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 resolved 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 queue 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 behaviour.

## `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&#39;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 artefacts require approval before the client can use 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** Framework-specific source globs

An array of glob patterns for source files scanned for inline content. React-family projects scan JavaScript and TypeScript under `src`, `app`, `pages`, and `components` by default. Vue projects also scan root `*.vue` files plus JavaScript, TypeScript, and Vue files in conventional Vue and Nuxt directories such as `composables`, `layouts`, `plugins`, `server`, `stores`, `utils`, and `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]

**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`.

When you use an alias, set `defaultLocale` and entries in `locales` to the alias name (`cn`), not the canonical name (`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`

Detects edits in previously downloaded local translation files and submits their diffs before [`gt translate`](/docs/cli/reference/commands/translate) or [`gt stage`](/docs/cli/reference/commands/stage) queues new work. Set it under the top-level `options` object. The `--save-local` and `--no-save-local` flags override this setting for one run.

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

### Version history

| Version  | Changes                                                                                      |
| -------- | -------------------------------------------------------------------------------------------- |
| `2.20.3` | Local edits became opt-in; set this key to `true` or pass `--save-local` to enable the step. |

## 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, for each 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 explicitly include or exclude matched files.

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

The CLI resolves publishing for any file 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.

## Locadex preserve local edits [#locadex-requirements]

When a Locadex automation has **Preserve local edits** enabled, configure either top-level `"publish": true` or `files.gt.output`. Locadex validates this before it runs translation.

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

Per-file and `files.gt.publish` settings do not satisfy this check. Without top-level CDN publishing, `files.gt.output` tells the workflow where local GTJSON translations are stored so it can preserve edits.

## 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`.

## Sitemap

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