GitHub Actions

When it runs

The workflow triggers when a PR changes your translation files. It compares your branch to the base branch, finds new or modified keys, translates them, and commits the results directly to your PR. See translations in the pull request for what that commit contains and how it affects CI.

What gets skipped

The action automatically skips translation when:

• • PR has a skip-translation label
• • PR is a draft
• • Commit was made by the LocalHero bot (prevents loops)

Since drafts are skipped, the workflow above also runs when you mark a draft PR as ready for review. That is what ready_for_review in its types line does. Without it, GitHub only starts the workflow when a PR is opened, gets new commits or is reopened. Your translations would then wait for the next push. The unlabeled type does the same when you remove a skip label.

If your workflow file doesn't have this line yet, add it under pull_request: and keep your paths:. List all five types, since setting them replaces the GitHub defaults:

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review, unlabeled]

Permissions

contents: write lets the action commit translations. pull-requests: write allows adding PR comments.

Gettext / PO files

For projects using gettext, run your message extraction before the action:

steps:
  - uses: actions/checkout@v7
    with:
      ref: ${{ github.head_ref }}
      fetch-depth: 0
      persist-credentials: false

  - uses: actions/setup-python@v5
    if: github.actor != 'localhero-ai[bot]'
    with:
      python-version: '3.11'

  - name: Extract messages
    if: github.actor != 'localhero-ai[bot]'
    run: |
      pip install -r requirements.txt
      python manage.py makemessages -a

  - uses: localheroai/localhero-action@v1
    with:
      api-key: ${{ secrets.LOCALHERO_API_KEY }}

Adjust the extraction command for your framework: xgettext for C/C++, pybabel extract for Flask, etc.

steps:
  - uses: actions/checkout@v7
    with:
      ref: ${{ github.head_ref }}
      fetch-depth: 0
      persist-credentials: false

  - uses: actions/setup-node@v4
    if: github.actor != 'localhero-ai[bot]'
    with:
      node-version: '22'

  - name: Extract messages
    if: github.actor != 'localhero-ai[bot]'
    run: |
      npm ci
      npx lingui extract

  - uses: localheroai/localhero-action@v1
    with:
      api-key: ${{ secrets.LOCALHERO_API_KEY }}

Manual trigger

The workflow includes workflow_dispatch, so you can run it manually from the Actions tab.

Stacked pull requests

When one pull request builds on another, each one translates only the keys it adds or changes. The Action compares your branch with the branch your pull request targets, not with main. Keys from the pull requests below yours don't get translated twice. The baseBranch setting in localhero.json only applies to runs outside a pull request. This needs CLI 0.0.92 or later. The Action uses the latest version unless you pin one with cli-version.

• • After the pull request below yours merges, yours gets a new target, usually main. Push a commit or close and reopen the pull request to translate against it. Re-running an old workflow run won't help. A re-run replays the original event, with a target branch that may already be deleted.
• • If two pull requests in the stack both got new translations, a rebase can conflict in the locale files. Keep both sides. They are different keys.