Enqueuing Translations for a File Subset with the General Translation CLI

gt enqueue queues translations for a project's configured files without uploading their source content, waiting for completion, or downloading output. Use a separate config to select a subset, and upload those exact source versions before enqueueing them.

What you will build

A translation request for getting-started.mdx in French and Spanish, leaving the project's other source files outside this request.

AI Prompt

Enqueue translations for only getting-started.mdx in a larger MDX project.

Requirements:
- Create gt.subset.config.json with an include pattern matching only that file.
- Keep the intended project, branch, locales, and output paths consistent.
- Use stageTranslations: false for this enqueue/download workflow.
- Upload the current selected source version, then enqueue with the same config.
- --force requests retranslation; it does not upload missing or changed sources.
- Check the selected jobs' completion and versions before verifying downloads.
- Run the verification step below before finishing.

Prerequisites

• A project with docs/en/getting-started.mdx and at least one other source file, such as docs/en/configuration.mdx

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

• A separate gt.subset.config.json:

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

Carry over any project-specific branch, review, and path settings needed from your main config. Keep its broader include patterns out of this subset config.

1. Check the selection

npx [email protected] translate --config gt.subset.config.json --dry-run

Confirm the source list contains only docs/en/getting-started.mdx, not docs/en/configuration.mdx.

2. Upload the selected version, then enqueue

npx [email protected] upload --config gt.subset.config.json
npx [email protected] enqueue --config gt.subset.config.json

Keep the source unchanged between these commands. Having uploaded the file at some earlier time is insufficient if its current content produces a new version. The upload step can also sync local translated copies that already exist.

For a version without existing translations, this selection can produce two jobs: one for French and one for Spanish. Existing translations can make some pairs a no-op. Use --force only when you intentionally want to retranslate an already-translated version.

Verify the result

In the dashboard, check the jobs for the selected source version and locales, and wait for completion and any required approval. Confirm that this request did not enqueue the unrelated configuration.mdx file. Then run:

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

Inspect docs/fr/getting-started.fr.mdx and docs/es/getting-started.es.mdx, checking their content and the version recorded in gt-lock.json. Save manual target-locale corrections first if you need to retain them before this forced download.

A download count alone does not prove the newly enqueued jobs completed: cached translations and pre-existing local files can obscure which version you are inspecting.

How it works

The config's include pattern controls which source references enqueue submits. Accepted translation jobs identify a file, version, branch, and target locale. The command returns after submitting work, while download is a separate operation against available translations.

Common issues

A source edit has not been uploaded

Run upload with the subset config again before enqueueing the edited version. --force does not replace this step.

More files are enqueued than intended

Check the subset config's include patterns with the dry run above. A broad pattern such as docs/[locale]/**/*.mdx selects the whole folder, not just the changed file.

A previous stage command changed download behavior

Keep stageTranslations: false in this subset config. In staged mode, download selects staged lockfile entries rather than the current configured file set.

Next steps

• Downloading translations once jobs complete
• Staging translations for approval

verification:
  status: needs_reverification
  reviewed_at: "2026-09-29"
  product_version: "gtx-cli 2.22.4"
  command: "npx [email protected] enqueue --config gt.subset.config.json"
  expected_result: "only the uploaded getting-started source version is requested for fr and es, and its completed translations are downloaded"
  evidence: "file selection and enqueue prerequisites reviewed in the implementation"
  remaining: "rerun the narrowed upload/enqueue/download workflow and inspect matching jobs and output"

Related Articles

• Localize a Project with General Translation's MCP Server
• Uploading Files with the General Translation CLI
• Keep Product Terminology Consistent Across Surfaces