# gt: General Translation CLI tool: Quickstart
URL: https://generaltranslation.com/en-GB/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 internationalisation 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, queuing, 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 when the selected setup needs them.

```bash
npx gt init
```

In a monorepo, run the command from the app you want to localise. The wizard stops without changing files when you run it from the workspace root.

<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 and chooses where translations are stored. When the selected setup needs credentials, it can write 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. If the wizard generated credentials, `.env.local` contains `GT_API_KEY` and `GT_PROJECT_ID`. The bundled-local Vite setup skips credentials, so add them in the next step before translating.*

### 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 manually: 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&#39;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 to 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