# gtx-cli: General Translation CLI tool: Configuration
URL: https://generaltranslation.com/en-US/docs/cli/reference/config.mdx
---
title: Configuration
description: Config docs for the gt.config.json file
---

## Overview

The `gt.config.json` file is used to configure your project's GT settings. It should be placed in the root of your project.

The CLI setup wizard [`npx gtx-cli init`](/docs/cli/init) will create a `gt.config.json` file for you in your project.

## Configuration

The `gt.config.json` file accepts the following properties, but is not limited to them:

- `defaultLocale`: The default locale for your project. This is the locale that your source content is written in. This is also the fallback locale for your project (if using `gt-next` or `gt-react`).

- `locales`: An array of locales for your project. These are the locales that you want to translate your project into. See the [supported locales](/docs/platform/supported-locales) for more information.
  If you are using `gt-next` or `gt-react`, these are also the locales that your app supports.

- `files`: This is an object that contains information about the content you want to translate.

- `stageTranslations`: An optional boolean flag that indicates whether your project is configured to use human review.

- `src`: An optional array of file glob patterns for your source files. By default, set to:

```json
[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]
```

- `dictionary`: An optional string that specifies the relative path to the dictionary file.

- `branchOptions`: An optional object for configuring branch-based translation tracking. See [branching](/docs/cli/branching) for more details.

<Callout type="info">
  To help validate your `gt.config.json` file, you can use the [JSON Schema](https://assets.gtx.dev/config-schema.json) for the CLI.

Add it to the top of your `gt.config.json` file:

```json title="gt.config.json" copy
{
  "$schema": "https://assets.gtx.dev/config-schema.json"
}
```

</Callout>

Here is an skeleton of the `gt.config.json` file:

```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"
}
```

### Locale aliasing

In the case you want to alias a locale (e.g. `cn` instead of `zh`), you can specify a custom mapping in the `gt.config.json` file.

```json title="gt.config.json"
{
  "customMapping": {
    // The alias locale
    "cn": {
      "code": "zh" // The official BCP 47 locale code
    }
  }
}
```

You can also specify different attributes for the aliased locale.

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

### Branch options

If you want to configure branching settings in your config file, you can use the `branchOptions` object:

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

| Property             | Description                                                                   | Default     |
| -------------------- | ----------------------------------------------------------------------------- | ----------- |
| `enabled`            | Enable branching for the project                                              | `false`     |
| `currentBranch`      | Override the current branch name (instead of auto-detect)                     | `undefined` |
| `autoDetectBranches` | Automatically detect branch relationships (incoming and checked-out branches) | `true`      |
| `remoteName`         | The git remote name used for branch detection                                 | `"origin"`  |

<Callout type="info">
  CLI flags take precedence over config file options. See the [branching guide](/docs/cli/branching) for more details.
</Callout>

---

## `files`

### Supported file types

`files` should contain a key for each file type that you want to translate.
You can configure your project to mix and match different file types, and have them all be translated.
We currently support the following file types:

- `gt`: General Translation files. Used by [`gt-next`](/docs/next), [`gt-react`](/docs/react), and [`gt-react-native`](/docs/react-native).
- `json`: JSON files.
- `yaml`: YAML files.
- `mdx`: Markdown component (MDX) files.
- `md`: Markdown (MD) files.
- `js`: JavaScript files.
- `ts`: TypeScript files.
- `html`: HTML files.
- `txt`: Text files.

Each file type should correspond to an object that contains one or more of the following keys:

- `include`
- `exclude`
- `transform`
- `output`

### `include`

If used, the value of the `include` key should be an array of glob patterns that match the files you want to translate.

You must use the `[locale]` placeholder in your glob patterns to ensure that source files are found correctly, and translated files are saved to the correct location.
The CLI tool will replace the `[locale]` placeholder with the `defaultLocale` value when searching for translatable files.

The CLI tool will save translated files to the corresponding path, with the `[locale]` placeholder replaced with the target locale code.

```json
{
  "include": ["docs/[locale]/**/*.json"]
}
```

### `exclude`

If used, the value of the `exclude` key should be an array of glob patterns that match the files you want to exclude from translation.

The pattern is the same as the `include` pattern, with the exception that the `[locale]` placeholder is optional. If provided, it will be replaced with the `defaultLocale` value.

```json
{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}
```

If you want to exclude files from translation for all locales, you can use the `[locales]` placeholder instead of `[locale]`.

```json
{
  "exclude": ["docs/[locales]/exclude/**/*.json"]
}
```

### `transform`

`transform` can either be a string or an object.

If `transform` is a string, it defines a remapping of the file name. It should contain a wildcard `*` that will be replaced with the original file name (anything before the first `.`).

For example, if you want the extension of all of your translated files to have `.[locale].json` instead of `.json`, you can use the following configuration:

```json
{
  "transform": "*.[locale].json"
}
```

Alternatively, if `transform` is an object, it should contain the following properties:

- `match` (optional): A regex pattern to match strings, supports capture groups
- `replace` (required): String or regex pattern to replace the match with

Both values support regex capture groups and are mapped to the full relative file name of the output file.

```json
{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}
```

For example, the above configuration will cause translated files to be saved under a target locale subdirectory.

#### Special Placeholders

The transform option supports several special placeholders that can be used in both `match` and `replace` strings:

- `{locale}`: The locale code placeholder that behaves differently depending on context:
  - **In `match` strings**: Replaced with the default locale code (e.g., `"en"`) to help identify source files
  - **In `replace` strings**: Replaced with the target locale code (e.g., `"fr"`, `"es"`) for the translated output files

For example, if your default locale is `"en"` and you're translating to `"fr"`:

- A `match` pattern of `"content/{locale}/file.md"` becomes `"content/en/file.md"`
- A `replace` pattern of `"content/{locale}/file.md"` becomes `"content/fr/file.md"`

Additionally, any other property from `getLocaleProperties` can be used as a placeholder with the same context-dependent behavior.

<Callout type="info">

This is useful if your docs or i18n framework requires a specific file extension for translated files instead of subdirectory-based locale routing.

</Callout>

### `output`

This key is exclusively used for General Translation files, specifically for saving translations locally. If you are using the GT CDN, this key is not needed.

The value should be a string containing a `[locale]` placeholder indicating the location where the translations will be saved.

For example, if you want to your Spanish translations to a file called `ui.es.json` in the `public/i18n` directory, you should use the following string:

```json
{
  "output": "public/i18n/[locale].json"
}
```

<Callout type="info">

This option should only be used if you are using `gt-next` or `gt-react`, and want to save translations locally, instead of using the GT CDN.

Currently, only one file for each locale can be generated.

</Callout>

---

### File type: `gt` [#gt]

**Supported Keys**

- `output` (Required)

**Example**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    }
  }
}
```

This configuration will tell the CLI tool to save your French and Spanish translations to the `public/i18n/[locale].json` directory.

By default, the CLI tool will not publish your translations to the GT CDN with this configuration.

---

### File type: `json` [#json]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}
```

Let's say your project's default locale is `en`, and you want to translate your project into `fr` and `es`.

With this configuration, the CLI will search for all JSON files under the subdirectory `json_files/en/` and save the translated files to `json_files/fr/` and `json_files/es/`.

It will ignore any files in the subdirectory `json_files/en/exclude/`.

---

### File type: `yaml` [#yaml]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}
```

Let's say your project's default locale is `en`, and you want to translate your project into `fr` and `es`.

With this configuration, the CLI will search for all YAML files under the subdirectory `yaml_files/en/` and save the translated files to `yaml_files/fr/` and `yaml_files/es/`.

It will ignore any files in the subdirectory `yaml_files/en/exclude/`.

---

### File type: `mdx` [#mdx]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}
```

This configuration will tell the CLI tool to search for all MDX files under the `content/docs/en` directory and save the translated files to the `content/docs/ja` directory.

The `transform` key causes the extension of the translated files to be changed to `.ja.mdx`.

---

### File type: `md` [#md]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```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"
    }
  }
}
```

This configuration will tell the CLI tool to search for all MD files under the `content/docs/en` directory and save the translated files to the `content/docs/ja` directory.

The `transform` key causes the extension of the translated files to be changed to `.ja.md`.

All files in the `content/docs/en/exclude` directory will be ignored.

---

### File type: `js` [#js]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "js": {
      "include": ["scripts/[locale]/**/*.js"]
    }
  }
}
```

This configuration will tell the CLI tool to search for all JavaScript files under the `scripts/en` directory and save the translated files to the `scripts/fr` and `scripts/es` directories.

---

### File type: `ts` [#ts]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "ts": {
      "include": ["scripts/[locale]/**/*.ts"]
    }
  }
}
```

This configuration will tell the CLI tool to search for all TypeScript files under the `scripts/en` directory and save the translated files to the `scripts/fr` and `scripts/es` directories.

---

### File type: `html` [#html]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```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"
    }
  }
}
```

This configuration will tell the CLI tool to search for all HTML files under the `content/docs/en` directory and save the translated files to the `content/docs/ja` directory.

The `transform` key causes the extension of the translated files to be changed to `.ja.html`.

All files in the `content/docs/en/exclude` directory will be ignored.

---

### File type: `txt` [#txt]

**Supported Keys**

- `include` (Required)
- `exclude` (Optional)
- `transform` (Optional)

**Example**

```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"
    }
  }
}
```

This configuration will tell the CLI tool to search for all text files under the `content/docs/en` directory and save the translated files to the `content/docs/ja` directory.

The `transform` key causes the extension of the translated files to be changed to `.ja.txt`.

All files in the `content/docs/en/exclude` directory will be ignored.

---

## Example configuration

Let's break down an example `gt.config.json` file:

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

In this example, we are translating the following files with a single call to [`gtx-cli translate`](/docs/cli/translate):

- All MDX files in the `content/docs/en` directory.
- All JSON files in the `resources/en` directory (excluding any files in the `resources/en/exclude` directory).
- All in-line `<T>` components in your React or Next.js project.
- Your `dictionary.[json|js|ts]` file.

GT: Translations will be saved to `public/i18n/es.json` and `public/i18n/fr.json`. These files can be loaded using [`loadTranslations`](/docs/react/api/config/load-translations).

MDX: Translations will be saved to the `content/docs/fr` and `content/docs/es` directories.
The file extensions will be changed to `.fr.mdx` and `.es.mdx` respectively (from `.mdx`).

JSON: Translations will be saved to the `resources/fr` and `resources/es` directories.

---

## Next steps

Learn how to use the [init command](/docs/cli/init) to generate this configuration file.