Localization in CI/CD with GitHub Actions and General Translation

Key takeaways

Commit gt.config.json, keep GT_API_KEY and GT_PROJECT_ID in CI secrets, and run npx gt translate before the production build.
Use npx gt validate as an early gate for supported framework and inline-library projects.
Split work into upload, enqueue, and download jobs when translation should not hold a build runner open.
Enable branch tracking so feature-branch translations stay isolated until merge.
Use Locadex when you want GitHub pull requests without maintaining a workflow file.

Why translation belongs in the pipeline

Out-of-band translation breaks as soon as the release cadence rises. A pull request changes source copy, the app ships, and target locales drift until someone remembers to export, translate, import, and review them. That is not a translation problem. It is an unowned build step.

Put localization next to linting, tests, and the production build. General Translation's CLI quickstart supports code, standalone JSON and YAML, plus Markdown and MDX. Keep generated translations in the repository when your deployment expects files, or configure your project to save results to the Translation CDN.

Pipeline design

Use the one-command path first. npx gt translate reads the committed configuration, sends configured source content, and saves results before the build.

Use separate jobs when your workflow needs an approval boundary or when the translation request should not keep a runner open:

Detect changed source content with your normal Git diff or path filters.
Validate supported inline content and dictionaries.
Upload source files with gt upload.
Queue work with gt enqueue. It returns without waiting for results.
Download completed translations with gt download in a later job.
Run your project build and tests.
Commit generated locale files to a bot branch, or let the configured output feed deployment.

The CLI documents these CLI quickstart. Start with the single command if Friday is the deadline. Split stages after the baseline works.

Walkthrough: the fastest GitHub Actions setup

1. Add the CLI and commit the configuration

Run the interactive setup locally, not inside CI. Then commit the generated configuration. For a framework project, this minimal CI configuration stores locale files locally.

npm install gt --save-dev
npx gt init

npm install gt --save-dev
npx gt init

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}

For standalone content, configure the relevant file type and include glob instead of, or alongside, the gt entry. Do not put credentials in this file.

2. Create repository secrets

Create a project API key and project ID, then store them as GT_API_KEY and GT_PROJECT_ID in GitHub Actions secrets. The key needs Files Write and Translation queue Enabled permissions for translation work.

GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id

GT_API_KEY=your-api-key
GT_PROJECT_ID=your-project-id

Expose those values only to the job environment.

env:
  GT_API_KEY: ${{ secrets.GT_API_KEY }}
  GT_PROJECT_ID: ${{ secrets.GT_PROJECT_ID }}

env:
  GT_API_KEY: ${{ secrets.GT_API_KEY }}
  GT_PROJECT_ID: ${{ secrets.GT_PROJECT_ID }}

3. Validate before requesting translations

Add validation before translation. On errors, the command exits non-zero and fails the job. It does not call the API.

npx gt validate --config gt.config.json

npx gt validate --config gt.config.json

4. Run translation on pull requests and pushes

Use the full translate flow to upload, queue, and download in one command. This is the shortest working path for a normal app repository.

name: localization

on:
  pull_request:
  push:
    branches: [main]

jobs:
  translate:
    runs-on: ubuntu-latest
    env:
      GT_API_KEY: ${{ secrets.GT_API_KEY }}
      GT_PROJECT_ID: ${{ secrets.GT_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx gt validate --config gt.config.json
      - run: npx gt translate --config gt.config.json
      - run: npm run build

name: localization

on:
  pull_request:
  push:
    branches: [main]

jobs:
  translate:
    runs-on: ubuntu-latest
    env:
      GT_API_KEY: ${{ secrets.GT_API_KEY }}
      GT_PROJECT_ID: ${{ secrets.GT_PROJECT_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx gt validate --config gt.config.json
      - run: npx gt translate --config gt.config.json
      - run: npm run build

5. Commit generated files only when your repository owns translations

If translation output lives in the repository, commit it from a protected bot workflow or open a pull request for review. Do not commit secrets.

git add -- public/_gt
if ! git diff --cached --quiet -- public/_gt; then
  git config user.name "localization-bot"
  git config user.email "[email protected]"
  git commit -m "chore: update translations"
  git push
fi

git add -- public/_gt
if ! git diff --cached --quiet -- public/_gt; then
  git config user.name "localization-bot"
  git config user.email "[email protected]"
  git commit -m "chore: update translations"
  git push
fi

If you need asynchronous stages instead, replace the single translate command with the documented CLI sequence below. Run download in a later job after translations are ready.

npx gt upload
npx gt enqueue
npx gt download

npx gt upload
npx gt enqueue
npx gt download

Branch and preview workflows

Enable branch tracking on pull-request jobs. The CLI detects the checked-out Git branch and associates new translations with it. Feature branches inherit existing translations from their base, while new translations remain attached to the feature branch until merge.

npx gt translate --config gt.config.json --enable-branching

npx gt translate --config gt.config.json --enable-branching

When CI cannot identify the branch, set it explicitly.

npx gt translate --enable-branching --branch my-feature-branch

npx gt translate --enable-branching --branch my-feature-branch

Follow the CLI branching guide for remote and branch-detection options. This keeps preview work distinct from main without re-translating shared content.

Alternative: agent-driven automation

Do not maintain a workflow file if a GitHub pull request is the interface your team already reviews. Use Locadex instead.

Connect the repository.
Select Generate code to add internationalization calls, Generate translations and push to translate updated source content, or Keep locales in sync when languages change.
Choose manual, pull-request-change, or pushed-commit triggers.
Review the setup pull request, merge it, then review the pull requests Locadex opens or updates.

The Locadex quickstart lists supported project types, setup, automation templates, triggers, and pull request behavior.

Quality gates

Put npx gt validate before translation. It checks supported inline content and dictionary syntax without calling the API, so syntax failures stop the pipeline before a translation request.

Use the Translation Editor for human review when copy needs sign-off. Use Context Groups to share a Glossary and Custom Prompts across product surfaces. When adding a glossary locale, use the Dashboard Translate flow to populate that locale's glossary column. Registering the locale alone does not populate it.

npx gt validate --config gt.config.json
npx gt translate --config gt.config.json
npm run build

npx gt validate --config gt.config.json
npx gt translate --config gt.config.json
npm run build

Cost

General Translation uses usage-based billing. The Starter plan has a $0 platform fee and includes unlimited projects, users, and languages, so adding reviewers or engineers does not create a per-seat cost. See pricing and the public usage rates before choosing the files and workflow to translate.

Limitations

Do not run npx gt init in CI. It is an interactive wizard and can wait for input or exit without creating configuration in a non-interactive shell.
gt validate is available for supported framework and inline libraries. It is not registered for base, non-framework projects.
gt enqueue does not wait for results. Schedule gt download later when you use split stages.
Branch tracking requires the Starter plan. Without it, a non-default branch falls back to the default branch.

FAQ

What is the fastest way to add localization to GitHub Actions?

Commit gt.config.json, add GT_API_KEY and GT_PROJECT_ID as secrets, then run npx gt validate --config gt.config.json and npx gt translate --config gt.config.json before npm run build.

Should translation block the production build?

Use npx gt translate when you need updated files in the same job. Use npx gt upload, npx gt enqueue, and npx gt download in separate jobs when translation should complete outside the active build job.

Can feature branches receive their own translations before merge?

Yes. Run npx gt translate --enable-branching in the pull-request job. New translations stay associated with the feature branch and are incorporated after merge.

Can we review translations before they land in the repository?

Yes. Stage work for review, approve it in the Translation Editor, then download approved translations. Use npx gt stage to submit work without downloading or publishing results in the same run.

Can we avoid maintaining GitHub Actions YAML?

Yes. Locadex can run its three localization automation templates manually, on pull-request changes, or on pushed commits, then open or update a pull request for the team to merge.

Put translation in the build

Start with the one-job workflow in this guide. Once it is green, split upload, enqueue, and download only where your review or deployment process needs that boundary. Your releases should not wait on a separate localization handoff.