# gt: General Translation CLI tool: gt download
URL: https://generaltranslation.com/en-GB/docs/cli/reference/commands/download.mdx
---

title: gt download
description: Download completed translations from General Translation. API reference for the gt download command.

---

Downloads completed translations that were previously sent for translation with [`gt enqueue`](/docs/cli/reference/commands/enqueue) or [`gt stage`](/docs/cli/reference/commands/stage), and saves them to the output paths in your config. See [Manage translations](/docs/cli/guides/managing-translations#split).

*Note: For production use only. Requires a production `GT_API_KEY` and `GT_PROJECT_ID`.*

```bash
npx gt download
```

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

1. Reads `gt.config.json` to determine the file configuration.
2. Reads staged version data when `stageTranslations` is enabled; otherwise collects and hashes files to determine what to download.
3. Polls the General Translation API for completed translations.
4. Saves translation files to the output paths in your config.

Files that are still processing are skipped. Re-run `gt download` to fetch them later.

## Flags [#flags]

`download` accepts the full [`gt translate`](/docs/cli/reference/commands/translate#flags) flag set, excluding the source-scanning flags (`--src`, `--dictionary`, `--tsconfig`/`--jsconfig`, `--inline`, `--ignore-errors`), which only apply when scanning source code. Every flag below is accepted; the ones that affect a download-only run are the API, config, timeout, download and branch 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>`             | Version ID to download.                                                                 | `string`   | Yes      | Content hash     |
| `-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...>`        | Additional target locales, appended to the config locales.                              | `string[]` | Yes      | —                |
| `--timeout <seconds>`           | Timeout to wait, in seconds.                                                            | `number`   | Yes      | `900`            |
| `--dry-run`                     | Parse and validate without calling the API.                                             | `boolean`  | Yes      | `false`          |
| `--force`                       | Invalidate cached translations and re-translate.                                        | `boolean`  | Yes      | `false`          |
| `--force-download`              | Overwrite local files, bypassing `gt-lock.json` checks.                                 | `boolean`  | Yes      | `false`          |
| `--save-local, --no-save-local` | Accepted by the shared flag parser, but does not save edits during a download-only run. | `boolean`  | Yes      | `true`           |
| `--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 it.                                               | `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`         |
| `--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      | —                |

`download` also accepts the experimental flags listed under [`gt translate`](/docs/cli/reference/commands/translate#experimental) (for example `--experimental-clear-locale-dirs`, which clears locale directories before writing new translations).

## Example [#example]

```bash
# Stage 1: upload source files
npx gt upload

# Stage 2: queue translations
npx gt enqueue

# Stage 3: download the completed translations (this command)
npx gt download
```

## Other notes [#notes]

* When `stageTranslations` is enabled, `download` reads the staged version data; otherwise it collects and hashes files to determine what to download.
* `download` polls the API until translations are ready or the `--timeout` is reached, so it can run in a later CI job than [`gt enqueue`](/docs/cli/reference/commands/enqueue).

- A staged file remains staged in `gt-lock.json` until every configured locale has been downloaded.
- `_versionId` is required only when the download includes an inline GTJSON template and `omitConfigIds` is `false`. File-only Projects, including Lottie-only Projects, do not need it.