Overview

In gtx-cli 2.3.0, we updated the behaviour of the translate and upload commands and improved visibility into the translation pipeline.

Translate

Historically, translate both triggered translations and ran a one-off project setup in the background (generating the context and glossary you see on your dashboard).

On smaller projects this was fast; on larger codebases, setup could take long enough to trigger a timeout, making it look as though there had been a translation failure.

While users were given the impression that translate had failed, setup would complete asynchronously and translations would be generated but not downloaded, leading to an incomplete and confusing UX.

Setup

Setup is now a separate step. We’ve optimised it to make timeouts rare.

But because we realise setup can still fail, translation no longer “depends” on setup finishing. Now the pipeline looks like this:

• Upload: send files and confirm success.
• Setup (only if needed): start a setup job and wait; if it fails or times out, we move on.
• Translate: create translation jobs based on the files you’ve already uploaded.

If setup completes in time, great. If it fails or times out, we continue and tell you what happened. You still get translations.

What you’ll see when you run npx gtx-cli translate:

Starting translation...

Files to translate:
  - your/file/path.mdx
  - ...

Uploading files to General Translation API...
✔ Files uploaded successfully

Setting up project...

# If setup succeeds
Setup successfully completed.

# If setup times out
⚠ Setup timed out — proceeding without setup: Timed out whilst waiting for setup generation

# If setup fails
⚠ Setup failed — proceeding without setup: <error message>

# In any case, we continue to translations
Creating 12 translation(s)
[0/12] translations completed
your/file/path.mdx [es]

With this change, we can now guarantee that your translations will be generated even in the unlikely event that setup fails.

We also like that it gives you more visibility into how and where we generate the content that influences your translations, and it makes adding new setup steps worry-free, since they will never stop translation from happening.

Upload

We've also made upload more flexible. Earlier versions assumed you always sent a source file together with its translations. That doesn't suit every workflow. Now you can:

• Upload source files only (no translations yet).
• Upload sources + translations together.

We still auto-detect translations from your repo structure and config. Once you upload, you'll immediately see files in your dashboard.

If this is your gt.config.json:

{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

Running npx gtx-cli upload:

# Sources only (no local translations found):
Starting upload...

Files to upload:
  - src/i18n/en/common.json -> es, fr
  ...

Uploading 1 file(s) to General Translation...
✔ Files uploaded successfully

Done!

# In your dashboard, you'll see:
#   src/i18n/en/common.json
# with no corresponding translations yet.

If local translations are present and automatically detected:

Starting upload...

Files to upload:
  - src/i18n/en/common.json -> es, fr

Uploading 3 file(s) to General Translation...
✔ Files uploaded successfully

Done!

# In your dashboard, you'll see:
#   src/i18n/en/common.json
# plus translated versions in Spanish and French in the locale drop-down.

If a locale's translation file is missing, we upload the source and skip that translation.

If you have local translations but only want to upload sources, remove locales from gt.config.json before running upload:

{
  "defaultLocale": "en",
  "locales": [],
  "files": {
    "json": { "include": ["src/i18n/en/**/*.json"] }
  }
}

Uploads overwrite existing translations

Heads-up: When you run upload, any translated file we detect and upload for a given file/locale replaces what is currently stored for that file/locale.

• To upload sources only, remove target locales from gt.config.json before upload.
• If you need to review changes first, use a separate project or export current translations before uploading.
• Missing translations are skipped; existing translations are replaced.