The GitHub Action

The transglot GitHub Action runs the CLI in a workflow. On each run it pushes your source strings, waits for the translation batch to finish, pulls the translated files, and commits them to the branch the workflow ran on. Reference it as transglot/transglot-action@v1; the v1 tag moves to each new release of the action.

Before you startCopy Anchor Link

1. Commit transglot.json to the repository. Run npx transglot@latest init in your checkout to write one, or see the configuration reference.
2. Create a deploy token with the push and pull abilities. With push alone the action uploads strings but cannot bring translations back. See Deploy tokens.
3. Add the token as a repository secret named TRANSGLOT_TOKEN, under Settings → Secrets and variables → Actions in GitHub. The token never goes in the workflow file.

Add the workflowCopy Anchor Link

Create .github/workflows/transglot.yml:

name: transglot
on:
  push:
    branches: [main]
jobs:
  localize:
    runs-on: ubuntu-latest
    permissions:
      contents: write # the action commits pulled translations back to a branch
    steps:
      - uses: actions/checkout@v7
      - uses: transglot/transglot-action@v1
        with:
          token: ${{ secrets.TRANSGLOT_TOKEN }}
          url: https://api.transglot.ai

The project's Releases page shows the same workflow in its Connect & SDK view, under GitHub Action: "Drop this into .github/workflows/transglot.yml and add TRANSGLOT_TOKEN to your repo secrets."

permissions: contents: write is required for the default commit mode. Without it, the commit step fails with a 403 because the job's token is read-only.

A commit made with the workflow's own GITHUB_TOKEN does not start another workflow run, so committing translations to main does not trigger this workflow again.

InputsCopy Anchor Link

The action accepts only these inputs. GitHub ignores an input the action does not declare and only prints a warning, so check the spelling if a setting seems to have no effect.

OutputsCopy Anchor Link

What a run doesCopy Anchor Link

1. Installs the CLI on Node.js 22, once per run.
2. Pushes your source files (transglot push, with --wait unless wait is "false"). With --wait, the step waits up to 600 seconds.
3. Pulls the translated files (transglot pull). It pulls when the push succeeded, when the word limit held the batch back (your sources are still synced), and when the batch failed, because translations that did complete can still be pulled. After any other error it skips the pull.
4. Commits or uploads the pulled files, depending on commit. In branch mode it stages only the files the pull wrote, commits as github-actions[bot] with the message chore(i18n): sync translations from transglot, and pushes. When nothing changed, or every pulled file is ignored by .gitignore, it skips the commit. In artifact mode it uploads them as an artifact named transglot-files.
5. Reports the result. The job fails with the worst CLI exit code of the push and the pull. Because this step runs last, a failed batch still commits the translations that finished and sets both outputs before the job turns red.

ExamplesCopy Anchor Link

Upload files as an artifactCopy Anchor Link

Use commit: artifact when the branch is protected, or to review the files before they land:

name: transglot
on:
  push:
    branches: [main]
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: transglot/transglot-action@v1
        with:
          token: ${{ secrets.TRANSGLOT_TOKEN }}
          commit: artifact

The run's summary page lists the transglot-files artifact. This mode needs no write permission.

Open a pull request with the translationsCopy Anchor Link

With commit: none the files stay in the workspace, so a later step can do anything with them. This workflow opens a pull request with a third-party action:

name: transglot
on:
  push:
    branches: [main]
jobs:
  localize:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
      - uses: transglot/transglot-action@v1
        id: transglot
        with:
          token: ${{ secrets.TRANSGLOT_TOKEN }}
          commit: none
      - if: steps.transglot.outputs.files_changed != '0'
        uses: peter-evans/create-pull-request@v8
        with:
          branch: transglot/translations
          commit-message: "chore(i18n): sync translations from transglot"
          title: Sync translations from transglot

Push now, pull on a scheduleCopy Anchor Link

Large batches can take longer than you want a merge job to run. Push without waiting on every merge, and pull on a schedule with the CLI's pull --wait, which waits for every active batch of the project:

name: transglot
on:
  push:
    branches: [main]
  schedule:
    - cron: "0 3 * * *"
jobs:
  push-strings:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npx --yes transglot@0.5.0 push
        env:
          TRANSGLOT_TOKEN: ${{ secrets.TRANSGLOT_TOKEN }}

  pull-translations:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npx --yes transglot@0.5.0 pull --wait --timeout 1800
        env:
          TRANSGLOT_TOKEN: ${{ secrets.TRANSGLOT_TOKEN }}
      - run: |
          if [ -n "$(git status --porcelain)" ]; then
            git config user.name "github-actions[bot]"
            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
            git add -A
            git commit -m "chore(i18n): sync translations from transglot"
            git push
          fi

Setting wait: "false" on the action is not the same: it pulls straight after pushing, before anything is translated. A locale with no translations yet then stops the pull, because pull refuses to overwrite an existing file with an empty one.

Use the outputsCopy Anchor Link

      - uses: transglot/transglot-action@v1
        id: transglot
        with:
          token: ${{ secrets.TRANSGLOT_TOKEN }}
      - if: steps.transglot.outputs.batch_id != ''
        run: echo "Translated in batch ${{ steps.transglot.outputs.batch_id }}, ${{ steps.transglot.outputs.files_changed }} file(s) changed"

TroubleshootingCopy Anchor Link