GitHub Actions CI recipe

Run translation in a trusted GitHub Actions job, inspect its artifacts, and add pull-request delivery when the output is ready.

Run the Lingo.dev CLI in GitHub Actions when translation needs to use your existing pipeline's triggers and checks. The runner reads your repository configuration, submits source changes, and downloads translated files. You control whether those files remain artifacts or become a pull request.

This recipe starts with manual dispatch and read-only repository access. Once you have inspected one changed message, you can add the write permissions needed for a translation pull request. The native GitHub App provides managed repository processing instead, without this runner recipe.

Prepare the repository #

Complete the CLI quickstart locally with one source file and one target language. Commit .lingo/config.json, the inspected target file, and .lingo/lock.json. The configuration selects the localization engine, source and target locales, and file patterns. The lockfile records the baseline for subsequent source changes.

For the example below, configure locales/en.json as the source and Spanish as the target, producing locales/es.json. The first missing target is created with lingo push --backfill-missing --wait; subsequent source edits use lingo push --wait. Backfill selects missing target files, so it is not a repair for missing keys inside an existing file.

Add LINGO_API_KEY to the repository or environment's Actions secrets. It grants Lingo.dev access, independently of GitHub repository permissions. Run the credentialed job only on trusted code. In particular, do not use pull_request_target to check out and execute an untrusted pull-request head with the secret.

The example pins the CLI version. To manage it through your project's dependencies and lockfile, follow the CI setup guide.

Obtain a translation artifact #

Save this as .github/workflows/translate.yml. The example uses Node.js 22.

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          test -s locales/es.json
          node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
          git diff -- locales/es.json .lingo/lock.json
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

Verify the organization and engine IDs in the committed .lingo/config.json. Make one English source edit, commit it, and dispatch the workflow from that trusted branch. Check the job log's run outcome and diff, then download the artifact and find the Spanish entry corresponding to your edit. Load it through the application and inspect its meaning and variables.

The upload includes hidden files so .lingo/lock.json is retained. Keep its path list limited to the intended target and lockfile; do not broaden it to include credentials or other private hidden files.

The shell checks establish file presence and JSON syntax. An old target file can pass both, so the changed-entry inspection matters. If the localization engine requires human review, the run can still be awaiting a person after the command returns. Before using that policy on a disposable runner, add the CI run-state preservation procedure. Export the specific run pointer and original absolute project root after submission, and upload .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, the target, and lockfile as restricted artifacts. Use if: always() on the export/upload steps so a later check failure does not discard recoverable state; a missing pointer means submission must be investigated, not invented.

After review, restore that exact revision and file state at the recorded absolute root, restore the pointer, authenticate separately, and use conflict-checked Pull. If another runner cannot recreate the path, submit and retrieve on a persistent authorized runner instead. Do not treat the first artifact's old target as the completed translation.

push --wait waits and downloads available completed output. Without --wait, push normally returns after submission. Separate submission and retrieval jobs need the same run-state export and restoration; copying the lockfile alone is insufficient. Keep downloaded targets and the lockfile from the same completed operation together, and never archive all of ~/.lingo.

Deliver a pull request #

After artifact inspection succeeds, grant the job contents: write and pull-requests: write. Repository policy must also allow Actions to create pull requests. GITHUB_TOKEN authorizes these GitHub operations; keep LINGO_API_KEY for translation.

Configure a Git identity under your team's bot policy. Then add a step after output validation that stages only the expected target and lockfile:

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

GitHub-hosted runners include the GitHub CLI. Supply GH_TOKEN from secrets.GITHUB_TOKEN to this step. The sequence assumes a trusted branch dispatch and a new branch name; a rerun with an existing branch needs an explicit reuse or replacement decision. It is not a fork-writeback workflow.

The pull request targets the branch from which you dispatched the job. If GitHub marks its workflows as awaiting approval, a repository writer must choose Approve workflows to run; see GitHub's GITHUB_TOKEN behavior. Review the translated diff, checks, and application output before merging.

Direct commits to the triggering branch are possible under a suitable branch policy, but remove this separate content-review step and need loop prevention.

Schedule work and handle monorepos #

Once the first run is useful, add trusted push branches and source-path filters. Generated translation commits must not continually trigger another translation job. Combine suitable branch or path filters with the no-change exit in the delivery step.

For a monorepo, set the translation step's working directory to the package containing .lingo/config.json. Update artifact and staged paths to include that package. A matrix can process independent packages, but two entries should not compete to update the same configuration and lockfile. Entries in one run share its run ID, so give each its own artifact name and translation branch, for example by adding the package name to translated-catalog and lingo/translations-${GITHUB_RUN_ID}.

Recover an incomplete run #

Start with the reported state: failed targets need their error resolved, awaiting-review targets need decisions, and local pull conflicts need a choice between the local edit and downloaded result. Keep successful output available for inspection while leaving incomplete locales unresolved. A partial result should not pass as a complete locale release.

Keep nonzero exits visible. || true, force-pulling over edits, or forcing every target can hide the cause and replace accepted work. The CI workflow guide explains how to preserve the revision and baseline during recovery.

Disable the workflow or its trigger to stop new runner jobs. If a job already submitted translation, inspect that server run separately when cancelling Actions. Remove unused secrets and repository write access when retiring the workflow.