# gt: General Translation CLI tool: gt translate
URL: https://generaltranslation.com/en-US/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'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` | Localize URLs in translated `md`/`mdx` files. | `boolean` | Yes | `false` |
| `--experimental-hide-default-locale` | Hide the default locale from localized paths. | `boolean` | Yes | `false` |
| `--experimental-flatten-json-files` | Flatten JSON files into a single file. | `boolean` | Yes | `false` |
| `--experimental-localize-static-imports` | Localize 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.