generaltranslation.com

Command Palette

Search for a command to run...

Translating a Project with the General Translation CLI

Last updated: 9/30/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Translating a Project with the General Translation CLI

gt translate runs the upload, translation, and download workflow for configured source files when stageTranslations is false. It uploads missing or changed source versions, can reuse existing translations, and writes available results to the configured output paths.

What you will build

A working end-to-end translation of a small MDX docs folder into two target locales, run first as a dry run and then for real.

docs/en/getting-started.mdx  --gt translate-->  docs/fr/getting-started.fr.mdx
                                                 docs/es/getting-started.es.mdx

AI Prompt

Translate a configured General Translation project into its target locales.

Requirements:
- Set stageTranslations: false for the normal upload/translate/download workflow.
- Run `gt translate --dry-run` first and confirm the selected source files.
- Run `gt translate` to upload missing or changed source versions, translate,
  and download the results to the configured output paths.
- A source content change produces a new version without requiring --force.
- Apostrophes may appear as ' in MDX; check rendered output.
- Run the verification step below before finishing.

Prerequisites

  • A gt.config.json at the project root. The examples below use:

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

    See the configuration doc for this example’s locale directory and output filename layout.

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

Note: Output below is trimmed; the real CLI output also includes a spinner and progress indicator escape sequences, omitted here for readability.

1. Dry run first

npx gtx-cli translate --config gt.config.json --dry-run

Real output:

◆  Dry run: No files were sent to General Translation.
│  Files found in project:
│  - docs/en/configuration.mdx
│  - docs/en/getting-started.mdx

2. Run the real translation

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

Real output (progress lines collapsed):

┌  Starting translation...
~  Project ID: prj_vk7ywgp89cc0qbzgxmx002fd
◇  Branch information resolved successfully
◇  Files uploaded successfully
◇  Done!

3. Inspect the translated output

find docs -type f | sort

Real output:

docs/en/configuration.mdx
docs/en/getting-started.mdx
docs/es/configuration.es.mdx
docs/es/getting-started.es.mdx
docs/fr/configuration.fr.mdx
docs/fr/getting-started.fr.mdx

cat docs/fr/getting-started.fr.mdx

Real output:

# Prise en main

Bienvenue dans le produit. Ce guide vous explique comment installer le CLI et
exécuter votre première commande.

## Installation

Exécutez le programme d'installation, puis vérifiez que le binaire figure bien dans votre PATH.

Verify the result

Edit a sentence in docs/en/getting-started.mdx so its meaning changes, then run a normal translation:

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

Confirm the French and Spanish output reflects the changed meaning and the lockfile identifies the new source version. Do not require an exact generated phrase. --force is not needed to detect a source content change.

How it works

translate resolves configured files and locales, identifies their source versions, uploads versions missing from the platform, and translates and downloads the needed output. Unchanged content can reuse existing translations. Markdown/MDX text is translated in segments and reassembled into its document structure.

Common issues

An apostrophe becomes ' in translated MDX

Translated MDX/Markdown output can contain the HTML entity ' in place of a literal apostrophe (for example, d'installation instead of d'installation). Most MDX renderers decode this correctly on render, but a plain-text diff or a non-MDX consumer of the same file will show the entity literally. Check rendered output, not just the raw file, when reviewing translation quality.

Re-running without --force after editing a source file

A source content change produces a new version automatically in the normal workflow. Use --force when you intentionally want to retranslate an existing version, not as a prerequisite for source edits. save-local saves manual edits to downloaded translations; it does not upload source edits.

If a previous stage command set stageTranslations: true, translate performs a staged download instead—even with --force. Run stage again to submit changed sources through that workflow, or set stageTranslations: false to resume normal translation.

Next steps

  • Staging translations for human approval instead of writing them directly
  • Enqueuing translations for a specific file subset
verification:
  status: needs_reverification
  product_version: "gtx-cli 2.22.4"
  command: "npx gtx-cli translate --config gt.config.json"
  expected_result: "an edited source version is translated without --force and the target output reflects the changed meaning"
  reviewed_at: 2026-09-29
  remaining: rerun the corrected verification against a test project

Related Articles