Staging Translations for Approval with the General Translation CLI

gt stage uploads and enqueues source files, records staged entries in gt-lock.json, and persists stageTranslations: true in the config. For the MDX workflow below, a human approval gate also requires requiresReview: true and the project's Auto approve translations setting to be disabled.

What you will build

A staged MDX translation that remains unavailable to the CLI download until a reviewer approves it.

AI Prompt

Stage a General Translation project's MDX translations for human approval.

Requirements:
- Set requiresReview to true for the files being reviewed.
- Disable Auto approve translations in the project dashboard and confirm
  the project info response has autoApprove: false.
- Run `gt stage`, which persists stageTranslations: true and staged entries.
- Wait for translation to complete, confirm an unapproved translation is
  held back, approve it, and then download it.
- A zero download count alone does not prove an approval gate.
- Run the verification step below before finishing.

Prerequisites

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

• A gt.config.json that requires review for these MDX files:

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

1. Disable automatic approval

In the project dashboard, disable Auto approve translations before staging. Confirm the setting:

npx [email protected] api "/v2/project/info/$GT_PROJECT_ID"

The response should include "autoApprove": false. This checks the project setting, not whether a particular translation has completed or been approved.

2. Stage the project

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

Use a new or changed source version for this example so there is work to review. The command uploads the selected sources and enqueues translations without downloading their output. Confirm gt.config.json now contains "stageTranslations": true and gt-lock.json contains the staged file entries.

3. Review, approve, and download

Wait until the dashboard shows the selected translations have completed. Before approving them, run:

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

A completed but unapproved translation covered by requiresReview should be held back. Approve the translation in the dashboard, then run the same download command again.

Verify the result

For the same source version and target locale, record these three states: translation completed but unapproved; download withheld before approval; and the expected translated content downloaded after approval. Check the output itself, not just the command's exit status or file count.

--force-download does not bypass the review gate. A zero count before a job finishes is evidence of pending work, not evidence that approval is enforced.

How it works

Staging separates enqueueing from downloading. The MDX review gate depends on both the file's requiresReview setting (false by default) and its approval state. Disabling automatic approval ensures newly completed translations await a reviewer; setting requiresReview: true makes the CLI respect that gate for these files.

stageTranslations also changes subsequent translate commands into downloads of staged entries. To submit another source change while keeping this workflow, run stage again. To return to the normal upload/translate/download workflow, set stageTranslations to false.

Common issues

Downloaded 0 files

Check job completion, approval status, and whether staged entries remain. Pending jobs, unapproved translations, and files already downloaded are different states; the count alone cannot distinguish them.

Translations download without a reviewer

Check both settings: requiresReview: true for these files and autoApprove: false on the project. stageTranslations: true alone does not establish a human approval gate.

Next steps

• Downloading translations that were staged
• Translating a project through the normal workflow

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"
  expected_result: "a completed unapproved review-required translation is withheld, then downloaded after approval"
  evidence: "stage persistence and download approval checks reviewed in the implementation"
  remaining: "rerun on a test project with requiresReview true and autoApprove false"

Related Articles

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