# gt: General Translation CLI tool: Quickstart
URL: https://generaltranslation.com/en-US/docs/cli/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Use the General Translation CLI to translate your project from the command line.

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.
- **API access** for authenticated raw requests and bundled OpenAPI discovery with [`gt api`](/docs/cli/reference/commands/api).
- **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 20 or later 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 [`gt init`](/docs/cli/reference/commands/init) to detect your framework, create `gt.config.json`, and optionally set up a project and development key. The wizard signs you in when that step needs it.

```bash
npx gt init
```

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

<Callout type="warn">
  Without a terminal, [`gt init`](/docs/cli/reference/commands/init) does not prompt. If answers are missing, it stops before changing files and lists the options to pass; see [headless runs](/docs/cli/reference/commands/init#headless). For CI, use [Non-interactive setup for CI](#ci-setup).
</Callout>

The wizard sets your default locale and target locales and chooses where translations are stored. It can also write a development key and project ID to `.env.local`. See [`gt init`](/docs/cli/reference/commands/init) for the full command.

*Note: You should now have a `gt.config.json` at your project root. The bundled-local Vite setup can skip sign-in and credentials; complete the next step before translating.*

### 3. Check your credentials

The [`translate`](/docs/cli/reference/commands/translate) command needs a project ID and your saved login or an API key. If setup skipped them, run [`gt login`](/docs/cli/reference/commands/login) and set your project ID:

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

(See [CLI credentials](/docs/cli/guides/configuring#credentials)).

### 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]

In CI, set up the project 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 project API key and project ID as environment variables in your CI provider's secret settings, not in a committed file. Create the key in the [Dashboard](/docs/platform/dashboard/reference/api-keys) or with [`gt api-key create`](/docs/cli/reference/commands/api-key-create), granting **Files > Write** and **Translation queue > Enabled** (add **Context > Write** if you generate context); the wizard's development key is not enough.

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

## Sitemap

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