Downloading Translations with the General Translation CLI

gt download pulls available translations into the paths described by gt.config.json. It complements enqueue and stage when translation and download happen in separate steps.

What you will build

A download step that checks translation readiness, plus a forced download that can replace existing local copies.

AI Prompt

Download previously enqueued or staged General Translation translations.

Requirements:
- Check completion and any required approval before expecting output.
- With stageTranslations false, download selects current configured source
  versions. With it true, download selects entries staged in gt-lock.json.
- --force-download allows selected translations to overwrite local copies;
  it does not create staged entries or bypass approval.
- Distinguish pending jobs, already-downloaded files, missing staged entries,
  approval holds, and actual download errors before retrying.
- Run the verification step below before finishing.

Prerequisites

• Uploaded source versions with translations enqueued or staged

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

• For a normal, non-staged enqueue/download workflow, a config like:

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

If you used stage, keep the stageTranslations: true setting and staged lockfile entries it created. In that mode, the staged versions determine what is selected for download.

1. Check readiness and download

Confirm in the dashboard that the intended file versions have finished translating. If the files require review, confirm approval too. Then run:

npx [email protected] download --config gt.config.json

The standalone command checks available translations; it does not wait on the jobs from an earlier enqueue command. If jobs are still pending, wait for them to finish before retrying. In automation, use bounded retries tied to job status rather than retrying every warning indefinitely.

2. Re-download selected translations when needed

npx [email protected] download --config gt.config.json --force-download

--force-download bypasses the check that normally skips an already-downloaded translation and allows its local copy to be overwritten. Save any manual translation corrections with save-local first if you want to retain them upstream.

With stageTranslations: false, current configured files remain selectable for re-download. With stageTranslations: true, only staged entries are selected; an entry is cleared once all its target locales have been downloaded. The flag cannot re-create those entries.

Verify the result

find docs -type f | sort

Check the expected paths, such as docs/fr/getting-started.fr.mdx, and inspect their translated content. Compare the file/version and locale recorded in gt-lock.json with the intended translation run. Existing files alone do not prove that a new run's output was downloaded.

The count is per source-file/target-locale pair: two source files and two target locales can produce four downloads. Already-downloaded, pending, or review-gated translations can reduce the count.

How it works

File selection happens before the overwrite check. Normal mode selects configured source versions; staged mode selects staged lockfile entries. The CLI then checks translation availability, any required approval, and whether the selected translation was already downloaded. --force-download changes the last of those checks.

Common issues

No files to download after a previous staged download

The staged entries may already be cleared. enqueue --force does not re-stage them. Run stage for the next staged batch, or deliberately use stageTranslations: false for a normal enqueue/download workflow.

Downloaded 0 files or a download warning

Check the specific warning and job state. A skipped file can be pending, already downloaded, or awaiting required approval. A failed-download warning can also indicate a missing version, a service failure, or a local write error. Investigate those failures rather than assuming every warning is a temporary translation delay.

Next steps

• Staging translations for approval
• Enqueuing translations for a specific file subset

verification:
  status: needs_reverification
  reviewed_at: "2026-09-29"
  product_version: "gtx-cli 2.22.4"
  command: "npx [email protected] download --config gt.config.json --force-download"
  expected_result: "the selected completed, approved translations are downloaded for the intended file versions"
  evidence: "selection and approval logic reviewed; local probe confirmed forced re-download works for an already-downloaded non-staged file"
  remaining: "rerun the corrected normal and staged workflows against a test project"

Related Articles

• Staging Translations for Approval with the General Translation CLI
• Translating a Project with the General Translation CLI
• Enqueuing Translations for a File Subset with the General Translation CLI