# gt: General Translation CLI tool: Configuring the CLI
URL: https://generaltranslation.com/en-US/docs/cli/guides/configuring.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to set up a General Translation gt.config.json with your locales, files, and storage options.

The CLI reads a `gt.config.json` file at the root of your project to decide what to translate and where results are saved. This guide shows how to create and edit that file.

*Note: This guide covers the common setup choices. For every available field, see the [configuration reference](/docs/cli/reference/config).*

## Create the config file [#create]

You can create `gt.config.json` three ways. Pick whichever fits your workflow.

### a) Run the full setup wizard

Run [`gt init`](/docs/cli/reference/commands/init) to detect your framework, configure files, and optionally provision a project and development runtime key. The wizard signs you in when that step needs it. Pass [flags](/docs/cli/reference/commands/init#flags) to answer its questions, or run it headless.

```bash
npx gt init
```

In a monorepo, run the command from the app you want to localize, not the workspace root. For Vite React apps, the wizard installs `gt-react`, configures [`initializeGTSPA`](/docs/react/reference/config#initialize-spa) before the existing app entry, and sets up local or CDN translation loading.

### b) Configure without the React setup step

Run [`gt configure`](/docs/cli/reference/commands/configure) to create or update `gt.config.json` without the experimental React framework rewrite. It shares the remaining setup flow with the full wizard: it can generate loaders, install the CLI, prompt for login, and provision development credentials.

```bash
npx gt configure
```

### c) Write it by hand

Create the file yourself and add the `$schema` reference for editor validation and autocompletion.

```json title="gt.config.json"
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}
```

## Set your locales [#locales]

Set `defaultLocale` to the language your source content is written in, and list your target languages in `locales`.

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

Both use standard locale codes such as `en`, `en-US`, or `zh`. See [supported locales](/docs/platform/dashboard/reference/supported-locales) for the full list.

To use a custom alias for a locale — for example `cn` instead of `zh` — add a `customMapping` entry pointing to the official code. Use the alias wherever you select that locale in `defaultLocale` or `locales`.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["cn", "fr"],
  "customMapping": {
    "cn": { "code": "zh" }
  }
}
```

## Choose which files to translate [#files]

Add a `files` object with a key for each file type you want to translate. Most types take an `include` array of glob patterns that use the `[locale]` placeholder to locate source files and to save translated ones. [`.xcstrings` catalogs](/docs/cli/reference/formats/xcstrings-files) are the exception because every locale is stored in one file that is updated in place.

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

The CLI replaces `[locale]` with `defaultLocale` when it searches for source files, and with each target code when it saves translations. Per-type options are documented under [File formats](/docs/cli/reference/formats/gt-jsx-files), and advanced matching is documented under [`include`](/docs/cli/reference/config#files).

## Choose where translations are stored [#storage]

If you use `gt-next`, `gt-react`, or `gt-react-native`, decide how translations are delivered.

- **Save locally** to bundle translations in your app. Add a `gt` entry with an `output` path that includes `[locale]`.
- **Publish to the CDN** to load translations at runtime instead of bundling them. Set `publish` to `true`.

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

(See [CDN publishing](/docs/cli/reference/config#cdn-publishing) to control publishing globally, per file, or per command).

## Add your credentials [#credentials]

### a) Sign in for local CLI work

1. Run [`gt login`](/docs/cli/reference/commands/login) and approve access in your browser. Use [`gt whoami`](/docs/cli/reference/commands/whoami) to check the account and [`gt logout`](/docs/cli/reference/commands/logout) to sign out.
2. Bind your app to a project with [`projectId`](/docs/cli/reference/config#project-id) in the existing `gt.config.json`, or set `GT_PROJECT_ID`. Login alone does not select or create a project. Use [`gt init`](/docs/cli/reference/commands/init) if you want guided selection or creation rather than manual binding.
3. Run [`gt translate`](/docs/cli/reference/commands/translate). Your account must have permission for each requested operation.

SDKs do not read your saved CLI login; configure runtime credentials separately.

### b) Use an explicit key for CI

Commit your config and provide `GT_API_KEY` through your CI provider's secret settings. Set the project ID in the config or environment. Login, including `--no-browser`, needs human approval. Headless [`gt init`](/docs/cli/reference/commands/init) runs unattended only when flags answer every question and it does not need to sign in.

```bash
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

Create a [custom project key](/docs/platform/dashboard/reference/api-keys#create-project-keys) or use [`gt api-key create`](/docs/cli/reference/commands/api-key-create) with explicit permissions. Grant permissions for the whole workflow: file reads/downloads, file writes/uploads, and translation enqueueing, plus context access when used. A generate-only runtime key is not sufficient for the translation pipeline. Never store API keys in `gt.config.json`; normal CLI settings validation rejects them.

### Credential precedence and environment files

Hosted commands prefer `--api-key`, then a nonempty `GT_API_KEY`, then the saved login when no explicit tooling key is supplied. Invalid or insufficient explicit keys never fall back to login. `GT_DEV_API_KEY` and its public-prefixed variants are runtime settings, not CLI management credentials. To use login, remove unwanted tooling keys from both the process environment and loaded env files; login does not clear them.

At startup, the executable loads `.env`, then `.env.local` with override, then `.env.production` with override. The last two files can replace an already exported key. For project binding and conflict checks, see [`projectId`](/docs/cli/reference/config#project-id).

### Development runtime keys

[`gt init`](/docs/cli/reference/commands/init) can provision a key with only `project:translations:generate` in ignored `.env.local`, using your framework's variable names. It does not replace `GT_API_KEY`. (See [Next.js credentials](/docs/react/nextjs/config#credentials) for runtime configuration).

<Callout type="warn">
  Never ship API keys in deployed browser or mobile bundles, even generate-only keys. (See [init file protections](/docs/cli/reference/commands/init#notes)).
</Callout>

## Next steps

- /docs/cli/guides/generating-translations
- /docs/cli/guides/managing-translations
- /docs/cli/guides/using-auto-jsx
- /docs/cli/guides/branching

## Sitemap

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