Saving Local Edits with the General Translation CLI

gt save-local saves manual edits to downloaded translations without enqueuing a new translation job. It compares target-locale files with the last downloaded versions recorded in gt-lock.json; it is not a way to upload edits to source content.

What you will build

A manual correction to a downloaded French MDX translation, saved upstream and verified against the platform's stored translation.

AI Prompt

Save a manual correction to a downloaded General Translation translation.

Requirements:
- Start with a translated file downloaded by the CLI and preserve gt-lock.json.
- Edit the target-locale output, keeping the source file unchanged for this test.
- Run `gt save-local` without starting a new translation job.
- Confirm the exact corrected text is stored for the same file, locale, and
  branch. A "Saved local edits" message alone does not prove a diff was sent.
- Run the verification step below before finishing.

Save a manual correction to a downloaded General Translation translation.

Requirements:
- Start with a translated file downloaded by the CLI and preserve gt-lock.json.
- Edit the target-locale output, keeping the source file unchanged for this test.
- Run `gt save-local` without starting a new translation job.
- Confirm the exact corrected text is stored for the same file, locale, and
  branch. A "Saved local edits" message alone does not prove a diff was sent.
- Run the verification step below before finishing.

Prerequisites

A gt.config.json covering the source file and its target-locale outputs, 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"
    }
  }
}

A downloaded translation such as docs/fr/getting-started.fr.mdx and the corresponding gt-lock.json download baseline
GT_API_KEY/GT_PROJECT_ID set as environment variables or passed via --api-key/--project-id

1. Edit a downloaded translation

Open docs/fr/getting-started.fr.mdx and correct a sentence in French. Record the exact before-and-after text so you can check it upstream. Leave docs/en/getting-started.mdx unchanged for this example.

2. Save the correction

npx [email protected] save-local --config gt.config.json

npx [email protected] save-local --config gt.config.json

The command can finish with Saved local edits even when there are no eligible translation diffs, so check the stored content before declaring success.

Verify the result

In the General Translation dashboard, select the same project, branch, source file/version, and French translation. Confirm that the stored translation contains the exact correction you made locally. If the correction is absent, check the locale's output path and the lockfile baseline before retrying.

Do not use translate --force to verify the save: it requests a new translation instead of proving that the manual correction was persisted.

How it works

save-local uses the source-file references to identify translations, then compares each configured target-locale output against its last downloaded content. It submits the resulting translation diffs without enqueuing a translation job. If publishing is configured, detected edits can also trigger publication.

Common issues

Editing only the source file

Changing only docs/en/getting-started.mdx does not create a target-locale diff for save-local to submit. Use upload to sync source content, or the normal translate workflow to upload and translate a changed source version.

Missing download baseline

Keep the lockfile generated by the CLI download. An arbitrary local translation without its corresponding downloaded baseline does not establish the comparison needed for this workflow.

Next steps

Uploading changed source files
Translating a project after source content changes

verification:
  status: needs_reverification
  reviewed_at: "2026-09-29"
  product_version: "gtx-cli 2.22.4"
  command: "npx [email protected] save-local --config gt.config.json"
  expected_result: "the stored French translation contains the exact manual correction"
  evidence: "source reviewed; local probe confirmed source-only edits submit no translation diff and target-locale edits do"
  remaining: "rerun the corrected workflow against a test project and inspect the stored translation"

verification:
  status: needs_reverification
  reviewed_at: "2026-09-29"
  product_version: "gtx-cli 2.22.4"
  command: "npx [email protected] save-local --config gt.config.json"
  expected_result: "the stored French translation contains the exact manual correction"
  evidence: "source reviewed; local probe confirmed source-only edits submit no translation diff and target-locale edits do"
  remaining: "rerun the corrected workflow against a test project and inspect the stored translation"