# gt: General Translation CLI tool: gt upload
URL: https://generaltranslation.com/en-US/docs/cli/reference/commands/upload.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Upload source files and translations to the General Translation platform. API reference for the gt upload command.

Uploads your project's source files and any existing translations to the General Translation platform, syncing local files so they can be managed, enqueued, and tracked. Pair it with [`gt enqueue`](/docs/cli/reference/commands/enqueue) and [`gt download`](/docs/cli/reference/commands/download) to split translation across CI stages. 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 upload
```

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

1. Reads `gt.config.json` to determine which files to upload.
2. Collects all translatable source files.
3. Hashes each file to generate a `fileId` (from its path) and `versionId` (from its content).
4. Queries the API to determine which files are new or changed.
5. Detects file moves — same content, different path — and preserves existing translations.
6. Uploads new and changed source files, along with any local translation files.
7. Applies configured CDN publish and unpublish rules. `--publish` sets publishing as the global default, while explicit per-file `publish: false` rules still opt files out.

## Flags [#flags]

`upload` registers the shared [translation flags](/docs/cli/reference/commands/translate#flags), but only uses the options relevant to collecting, uploading, and publishing files. The main options are below.

| 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` |
| `-c, --config <path>` | Path to the config file. | `string` | Yes | `gt.config.json` |
| `--locales <locales...>` | Extra target locales, appended to config locales. | `string[]` | Yes | — |
| `--default-locale <locale>` | Source locale for the project. | `string` | Yes | `en` |
| `--publish` | Use publishing as the global default; explicit per-file opt-outs still apply. | `boolean` | Yes | `false` |

<Callout type="warn">
  In `gt` 2.20.1, `upload` accepts `--dry-run` but still uploads files. Its shared `--timeout` flag controls translation waiting and has no effect on this command. To inspect collected files without uploading them, use [`gt stage --dry-run`](/docs/cli/reference/commands/stage).
</Callout>

## Example [#example]

```bash
# Stage 1: upload source files (this command)
npx gt upload

# Stage 2: enqueue translations
npx gt enqueue

# Stage 3: download when ready
npx gt download
```

## Other notes [#notes]

- `upload` collects translatable source files of every configured type (JSON, YAML, Markdown, MDX, and more) and any local translation files.
- Existing translations whose content still matches `gt-lock.json` are skipped. Other local translations are uploaded and can replace the stored translations; without a lock file, all local translations are uploaded.
- Because it hashes each file by path and content, moved files (same content, new path) keep their existing translations instead of being re-translated.
- Enable the CDN in your project settings before publishing. If publishing fails, the upload remains successful and the CLI emits a warning.

## Sitemap

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