Uploading Files with the General Translation CLI

gt upload sends a project's configured source files (and any local translated copies already present) to the General Translation platform without necessarily writing anything back to the local codebase in the same step, which makes it useful as a standalone sync step in a pipeline that separates "get content onto the platform" from "get translations back."

What you will build

An upload call against the same configured project used in the other CLI docs, confirming the platform receives both source and any locally-edited translation files.

AI Prompt

Upload a General Translation project's source and local translation files to
the platform using the CLI, as a standalone step separate from downloading.

Requirements:
- `gt upload` reports the number of translation files it uploads, separate
  from the initial "syncing" step that uploads source files.
- Run the verification step below before finishing.

Upload a General Translation project's source and local translation files to
the platform using the CLI, as a standalone step separate from downloading.

Requirements:
- `gt upload` reports the number of translation files it uploads, separate
  from the initial "syncing" step that uploads source files.
- Run the verification step below before finishing.

Prerequisites

A gt.config.json like:

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "mdx": {
      "include": ["docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "mdx": {
      "include": ["docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}

GT_API_KEY/GT_PROJECT_ID set as environment variables or passed via --api-key/--project-id

1. Upload

npx gtx-cli upload --config gt.config.json

npx gtx-cli upload --config gt.config.json

Real output (progress lines collapsed):

┌  Starting upload...
│  Files to upload:
│    - docs/en/configuration.mdx -> fr, es
│    - docs/en/getting-started.mdx -> fr, es
◇  Branch information resolved successfully
◇  Files uploaded successfully
◇  Uploaded 2 translation files, skipped 2 unchanged
◆  All files uploaded successfully
└  Done!

The exact wording depends on how many of the project's local translation files differ from what's already on the platform:

No local translation files exist yet for any source file: the "Files to upload" list shows plain filenames with no -> fr, es suffix, and no "Uploaded"/"unchanged" line appears at all before "All files uploaded successfully".
First upload once local translation files exist: Uploaded N translation files, no skipped clause.
A later upload where some translations already match: Uploaded X translation files, skipped Y unchanged.
A later upload where every local translation file matches what's already synced: All N translation files are unchanged since the last sync... skipping upload translations step.

The -> fr, es locale annotation in the "Files to upload" list only appears once local translation files for those locales already exist.

Verify the result

Before uploading, record a recognizable sentence from one selected source file and, if present, one local translated copy. After the command succeeds, open the same project and branch in the General Translation dashboard.

Locate the uploaded source file/version and confirm its stored content matches the source sentence. Then open the corresponding target-locale translation and confirm the local translated sentence was stored too. Check every file/locale whose upload you need to verify; the source sync message and translation-file counts describe separate parts of the operation.

/v2/project/info/$GT_PROJECT_ID reports project metadata such as locale settings. It does not list uploaded file versions or their content, so matching defaultLocale and currentLocales is not proof that the upload succeeded.

How it works

upload performs the source-file sync step that translate/stage also perform internally, plus an upload of any local translation files already present under the paths transform describes. It is the piece of the pipeline that gets content onto the platform; it does not by itself wait for or fetch newly generated translations the way translate or download do.

Common issues

The uploaded count changes between the first and later uploads

upload's reported count is not a fixed property of the config; it reflects how many local translation files actually differ from what the platform already has. Do not treat a lower count on a later run, or the appearance of a "skipped N unchanged" clause, as a sign that files went missing.

Next steps

Enqueuing translations after uploading the current source versions
Downloading translations once translation jobs are complete

verification:
  status: needs_reverification
  product_version: "gtx-cli 2.22.4"
  command: "npx gtx-cli upload --config gt.config.json"
  expected_result: "the exact uploaded source and local translation content is visible for the correct project, branch, file, version, and locale"

verification:
  status: needs_reverification
  product_version: "gtx-cli 2.22.4"
  command: "npx gtx-cli upload --config gt.config.json"
  expected_result: "the exact uploaded source and local translation content is visible for the correct project, branch, file, version, and locale"
  reviewed_at: 2026-09-29
  remaining: rerun the corrected verification against a test project