# gt: General Translation CLI tool: gt translate
URL: https://generaltranslation.com/en-GB/docs/cli/reference/commands/translate.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Translate a project through the General Translation API. API reference for the gt translate command.

Translates your project. It reads `gt.config.json` to find your files, scans your source code for inline content when you use a framework library, includes your dictionary, and saves translations to your codebase or the CDN.

This is the primary command for using the General Translation API. Run it in CI before a production build. For the full workflow, see [Generating translations](/docs/cli/guides/generating-translations). Under the hood, `translate` stages and downloads in one step; to run those parts separately, use [`gt stage`](/docs/cli/reference/commands/stage), [`gt upload`](/docs/cli/reference/commands/upload), [`gt enqueue`](/docs/cli/reference/commands/enqueue), and [`gt download`](/docs/cli/reference/commands/download). Lottie animations must be staged before a later download because their layout processing is asynchronous.

*Note: For production use only. Set a production `GT_API_KEY` and `GT_PROJECT_ID` as environment variables, and never store your API key in `gt.config.json`.*

```bash
npx gt translate
```

## How it works [#how-it-works]

1. Reads `gt.config.json` to determine the target locales, the files to translate, and their output paths.
2. For `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start`, and `gt-vue` projects, scans your `src` globs for inline content. This includes React-family [`<T>`](/docs/react/reference/components/t) components and [`useGT`](/docs/react/reference/hooks/use-gt) calls, along with Vue templates and module-level [`t()`](/docs/vue/reference/functions/t) calls, and includes your dictionary file.
3. Auto-detects a third-party i18n library from `package.json` — `next-intl` or `i18next` (with `i18next-icu` support) — and translates its JSON files while respecting that library&#39;s syntax.
4. Stages the collected content with [`gt stage`](/docs/cli/reference/commands/stage): it uploads sources, optionally detects and saves local edits when `--save-local` or [`options.saveLocal: true`](/docs/cli/reference/config#save-local) is set, then enqueues translation jobs. Because Lottie layout processing is asynchronous, a project with `.lottie` files exits before this step when `stageTranslations` is `false`, without uploading or enqueuing anything, and directs you to the split flow.
5. Downloads the results with [`gt download`](/docs/cli/reference/commands/download). Use the split commands to run staging and download separately.
6. Saves translations to your codebase, and to the CDN when `--publish` or the [`publish`](/docs/cli/reference/config#publish) config key is set.

By default, the CLI does not sync local translation edits before starting new work. Pass `--save-local` to sync them, `--force` to re-translate everything, or `--force-download` to re-download without re-translating.

## Flags [#flags]

| Parameter                       | Description                                                          | Type       | Optional | Default          |
| ------------------------------- | -------------------------------------------------------------------- | ---------- | -------- | ---------------- |
| `--api-key <key>`               | Production API key.                                                  | `string`   | Yes      | `GT_API_KEY`     |
| `--project-id <id>`             | project ID.                                                          | `string`   | Yes      | `GT_PROJECT_ID`  |
| `--version-id <id>`             | Accepted but has no effect; see the note below.                      | `string`   | Yes      | —                |
| `-c, --config <path>`           | Path to the config file.                                             | `string`   | Yes      | `gt.config.json` |
| `--default-locale <locale>`     | Source locale for the project.                                       | `string`   | Yes      | `en`             |
| `--locales <locales...>`        | Extra target locales, appended to config locales.                    | `string[]` | Yes      | —                |
| `--timeout <seconds>`           | Translation wait timeout in seconds.                                 | `number`   | Yes      | `900`            |
| `--dry-run`                     | Parse and validate without calling the API.                          | `boolean`  | Yes      | `false`          |
| `--force`                       | Re-translate all content, overwriting existing translations.         | `boolean`  | Yes      | `false`          |
| `--force-download`              | Re-download all translations, overwriting local changes.             | `boolean`  | Yes      | `false`          |
| `--save-local, --no-save-local` | Enable or disable saving local edits before enqueuing.               | `boolean`  | Yes      | `false`          |
| `--publish`                     | Publish translations to the CDN.                                     | `boolean`  | Yes      | `false`          |
| `--enable-branching`            | Enable branch-based tracking.                                        | `boolean`  | Yes      | —                |
| `--branch <branch>`             | Branch name instead of auto-detecting. Implies `--enable-branching`. | `string`   | Yes      | —                |
| `--disable-branch-detection`    | Use only the specified branch, without relationship detection.       | `boolean`  | Yes      | `false`          |
| `--remote-name <name>`          | Git remote used for branch detection.                                | `string`   | Yes      | `origin`         |
| `--omit-config-ids`             | Do not write `_versionId` or `_branchId` to `gt.config.json`.        | `boolean`  | Yes      | —                |
| `--tag [value]`                 | Tag the run; auto-resolves from git when no value is given.          | `string`   | Yes      | —                |
| `-m, --message <message>`       | Message attached to the translation tag.                             | `string`   | Yes      | —                |

### Source scanning flags [#source]

These apply when scanning source code in `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start`, and `gt-vue` projects.

| Parameter                       | Description                                                                                                                   | Type       | Optional | Default                  |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- | ------------------------ |
| `--src <paths...>`              | Glob patterns for source files.                                                                                               | `string[]` | Yes      | Framework-specific globs |
| `--dictionary <path>`           | Path to the dictionary file.                                                                                                  | `string`   | Yes      | —                        |
| `--tsconfig, --jsconfig <path>` | Path to a TS or JS config file.                                                                                               | `string`   | Yes      | Auto-detected            |
| `--inline`                      | Include inline content such as [`<T>`](/docs/react/reference/components/t) and [`useGT`](/docs/react/reference/hooks/use-gt). | `boolean`  | Yes      | `true`                   |
| `--ignore-errors`               | Ignore errors found while scanning inline content.                                                                            | `boolean`  | Yes      | `false`                  |

### Experimental flags [#experimental]

| Parameter                                 | Description                                                       | Type      | Optional | Default |
| ----------------------------------------- | ----------------------------------------------------------------- | --------- | -------- | ------- |
| `--experimental-localize-static-urls`     | Localise URLs in translated `md`/`mdx` files.                     | `boolean` | Yes      | `false` |
| `--experimental-hide-default-locale`      | Hide the default locale from localised paths.                     | `boolean` | Yes      | `false` |
| `--experimental-flatten-json-files`       | Flatten JSON files into a single file.                            | `boolean` | Yes      | `false` |
| `--experimental-localize-static-imports`  | Localise static imports in `md`/`mdx` files.                      | `boolean` | Yes      | `false` |
| `--experimental-localize-relative-assets` | Rewrite relative image asset URLs in translated `md`/`mdx` files. | `boolean` | Yes      | `false` |
| `--experimental-clear-locale-dirs`        | Clear locale directories before downloading.                      | `boolean` | Yes      | `false` |

## Example [#example]

```bash
# Translate using gt.config.json, reading GT_API_KEY and GT_PROJECT_ID from the environment
npx gt translate

# Parse and validate the project without calling the API
npx gt translate --dry-run

# Save translations locally and publish them to the CDN for runtime loading
npx gt translate --publish

# Tag the run so it is easy to identify in the Dashboard
npx gt translate --tag v2.1.0 -m "Added checkout page translations"
```

## Other notes [#notes]

* **Content sources:** the CLI uses framework-specific defaults. React-family projects scan `src`, `app`, `pages`, and `components`; Vue projects also cover root `.vue` files and conventional Vue and Nuxt directories. Override them with `--src` or the [`src`](/docs/cli/reference/config#src) config key.
* **Dictionary:** when `--dictionary` is not set, the CLI looks for `dictionary.[json|ts|js]` in `./src` and `./`.
* **Local edits:** local-edit syncing is off by default. Pass `--save-local` for one run or set [`options.saveLocal`](/docs/cli/reference/config#save-local) to `true`.
* **Overwriting:** `--force` overwrites all existing translations and bills for new ones; `--force-download` overwrites local edits with the latest translations without re-translating.
* **Lottie:** translate animations with [`gt stage`](/docs/cli/reference/commands/stage), then re-run [`gt download`](/docs/cli/reference/commands/download) until every locale is ready. See the [Lottie format reference](/docs/cli/reference/formats/lottie-files).
* **Tagging:** tagging is non-blocking — if tag creation fails, the run continues. Pass `--tag` with no value to use the current git commit hash and message.
* **Publishing:** enable the CDN in your project settings before using `--publish`. If the CDN is not enabled, the run translates successfully, but the publish step fails with a warning.
* **Branching:** pass `--enable-branching` to track translations per git branch, or pass `--branch <name>`, which enables branching on its own. When neither flag is set, the CLI falls back to `branchOptions.enabled` in `gt.config.json`, and to off if that is unset. See [Tracking translations by branch](/docs/cli/guides/branching).
* **`--version-id` has no effect.** The flag is parsed but nothing reads it: version IDs are per-file content hashes, and the commands that need a run-level version read `_versionId` from `gt.config.json`. Set [`_versionId`](/docs/cli/reference/config) there instead.
* **Security:** never store your API key in `gt.config.json`. The CLI reads `GT_API_KEY` and `GT_PROJECT_ID` from the environment automatically.

### Version history

| Version  | Changes                                                       |
| -------- | ------------------------------------------------------------- |
| `2.20.3` | Local edits became opt-in; `--save-local` enables the step.   |
| `2.16.1` | Local edits are saved by default; `--no-save-local` opts out. |

## Sitemap

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