# gt: General Translation CLI tool: Quickstart
URL: https://generaltranslation.com/en-US/docs/cli/quickstart.mdx
---

title: Quickstart
description: Learn what the General Translation CLI does, when to use it, and how to translate your first project.
related:
  links:
    - /docs/cli/guides/generating-translations
    - /docs/cli/guides/configuring
    - /docs/cli/guides/managing-translations
    - /docs/cli/guides/using-auto-jsx

---

The General Translation CLI (`gt`) sets up internationalization and translates your project from the command line.

It works with [`gt-react`, `gt-next`, and `gt-react-native`](/docs/react/overview), with third-party i18n libraries like `next-intl` and `i18next`, and with standalone files such as JSON, YAML, Markdown, and MDX.

## What the CLI does [#what-it-does]

The CLI gives you direct access to:

- **Setup** for installing dependencies, wiring up your framework, and creating a `gt.config.json`.
- **Translation** for sending your source content to the General Translation API and saving the results to your codebase or the CDN.
- **CI building blocks** for uploading, enqueuing, and downloading translations across separate pipeline stages.
- **Validation** for checking your project for translation errors without calling the API.

## When to use the CLI [#when-to-use]

Use the CLI when you want to:

- Set up a new project for translation with a guided wizard.
- Translate your project as part of a build or CI pipeline.
- Translate standalone content files without adding a framework library.
- Keep translations in version control alongside your source content.

## Quickstart [#quickstart]
Install `gt`, configure your project, and run your first translation. You need an existing project with a `package.json` and Node.js installed.

### 1. Install `gt`

Install the CLI as a dev dependency.

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt --save-dev
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add --dev gt
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add --dev gt
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add --save-dev gt
    ```
  </Tab>
</Tabs>

### 2. Configure your project

Run the setup wizard to detect your framework, create a `gt.config.json`, and generate credentials.

```bash
npx gt init
```

<Callout type="warn">
  [`gt init`](/docs/cli/reference/commands/init) is an interactive wizard and needs a terminal. In CI or another non-interactive shell it may wait for input, fail validation, or exit early without creating `gt.config.json` or writing credentials. For those environments, use [Non-interactive setup for CI](#ci-setup).
</Callout>

The wizard sets your default locale and target locales, chooses where translations are stored, and writes your API key and Project ID to `.env.local`. See [Configuring the CLI](/docs/cli/guides/configuring) to set this up in detail, or [`gt init`](/docs/cli/reference/commands/init) for the full command.

*Note: You should now have a `gt.config.json` at your project root and a `.env.local` file containing `GT_API_KEY` and `GT_PROJECT_ID`.*

### 3. Add your production API key

The [`translate`](/docs/cli/reference/commands/translate) command requires a production API key and Project ID. The wizard can generate these for you, or create them on the [API Keys page](https://generaltranslation.com/dashboard). Set them as environment variables so the CLI can read them.

```bash title=".env.local"
GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id
```

*Note: Set your API key as an environment variable — never add it to `gt.config.json`.*

### 4. Translate your project

Run the [`translate`](/docs/cli/reference/commands/translate) command to translate every file configured in `gt.config.json`, along with any inline [`<T>`](/docs/react/reference/components/t) components and dictionary entries in your source code.

```bash
npx gt translate
```

Translations are saved to your codebase, ready to commit. Run this in your CI pipeline before you build for production. See [Generating translations](/docs/cli/guides/generating-translations) for the full workflow.

## Non-interactive setup for CI [#ci-setup]

The setup wizard needs an interactive terminal, so it cannot run in CI or other non-interactive environments. Set those up by hand: commit a `gt.config.json`, provide your credentials as environment variables, and run [`translate`](/docs/cli/reference/commands/translate) against that config.

### 1. Add a `gt.config.json`

Write the file yourself and commit it so the CLI knows what to translate. A minimal config sets the source and target locales and a `files` entry so [`translate`](/docs/cli/reference/commands/translate) has something to work on. The `gt` entry below stores framework translations (from `gt-next`, `gt-react`, or `gt-react-native`) locally at the given path.

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

To translate standalone files instead, add a file type such as `json` or `mdx` with an `include` glob in place of (or alongside) the `gt` entry. See [Configuring the CLI](/docs/cli/guides/configuring) for the file and storage options, and the [configuration reference](/docs/cli/reference/config) for every field.

### 2. Set your credentials

Set your production API key and Project ID as environment variables in your CI provider's secret settings, not in a committed file. Create them on the [API Keys page](https://generaltranslation.com/dashboard).

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

### 3. Run the translate command

Run [`translate`](/docs/cli/reference/commands/translate) before you build for production. Pass `--config` to point at your config file.

```bash
npx gt translate --config gt.config.json
```

## Next steps

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