GitHub

Lingo.dev supports two ways to run continuous localization on GitHub: the managed GitHub App, and running the @lingo.dev/cli inside a GitHub Actions job.

Which one should I use?

Start with the GitHub App - it runs server-side, reacts to pushes and pull requests automatically, and needs no runner, no API key secret, and no lockfile management. Reach for GitHub Actions when you want localization to run inside your own pipeline alongside other CI steps.

GitHub App (recommended)#

The GitHub App is the easiest way to run continuous localization on GitHub. Install it once, point it at an engine, and it reacts to every push and pull request.

Install the app from the GitHub App page and grant it access to your repository.
Commit a .lingo/config.json at the repository root describing your buckets and locales, including the engineId of the engine the app should use. See Configuration for the file format.
Push. The app localizes changed content server-side and commits the results back (or opens a pull request), keeping .lingo/lock.json up to date automatically.

Because the app runs server-side, there is no runner to maintain, no LINGO_API_KEY secret to store, and no lockfile command to run.

GitHub Actions#

To run localization in your own pipeline, install the CLI in a job and run lingo push, then commit the results or open a pull request with your existing tooling.

Store your API key as a repository secret named LINGO_API_KEY (Settings > Secrets and variables > Actions). The CLI reads it from the environment.

Commit to the current branch#

Create .github/workflows/localize.yml:

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          git add .
          git diff --staged --quiet || git commit -m "feat: update translations"
          git push

This localizes changed content and commits the results directly to the branch on every push.

Open a pull request#

To land translations through review instead of committing directly, push the results to a branch and open a pull request. This example uses the GitHub CLI, which is preinstalled on GitHub-hosted runners:

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Open pull request
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          branch="lingo/translations-${{ github.run_id }}"
          git checkout -b "$branch"
          git add .
          git diff --staged --quiet && exit 0
          git commit -m "feat: update translations"
          git push origin "$branch"
          gh pr create --fill --base "${{ github.ref_name }}" --head "$branch"

Enable Settings > Actions > General > Allow GitHub Actions to create and approve pull requests for PR-based workflows.

The same job works on feature branches - change the on.push.branches filter (for example branches-ignore: [main]) to control where localization runs.

Next Steps#

GitHub App

Managed alternative - no runner, secret, or lockfile

CLI reference

Commands, configuration, and CI usage

Advanced Patterns

Localization checks, merge conflicts, workflow selection

GitLab CI/CD

Set up GitLab CI/CD integration

Lingo.dev supports two ways to run continuous localization on GitHub: the managed GitHub App, and running the @lingo.dev/cli inside a GitHub Actions job.

Which one should I use?

GitHub App (recommended)#

The GitHub App is the easiest way to run continuous localization on GitHub. Install it once, point it at an engine, and it reacts to every push and pull request.

Install the app from the GitHub App page and grant it access to your repository.
Commit a .lingo/config.json at the repository root describing your buckets and locales, including the engineId of the engine the app should use. See Configuration for the file format.
Push. The app localizes changed content server-side and commits the results back (or opens a pull request), keeping .lingo/lock.json up to date automatically.

Because the app runs server-side, there is no runner to maintain, no LINGO_API_KEY secret to store, and no lockfile command to run.

GitHub Actions#

To run localization in your own pipeline, install the CLI in a job and run lingo push, then commit the results or open a pull request with your existing tooling.

Store your API key as a repository secret named LINGO_API_KEY (Settings > Secrets and variables > Actions). The CLI reads it from the environment.

Commit to the current branch#

Create .github/workflows/localize.yml:

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          git add .
          git diff --staged --quiet || git commit -m "feat: update translations"
          git push

This localizes changed content and commits the results directly to the branch on every push.

Open a pull request#

yaml

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Lingo.dev CLI
        run: npm install -g @lingo.dev/cli
      - name: Localize
        run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Open pull request
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.name "Lingo.dev"
          git config user.email "support@lingo.dev"
          branch="lingo/translations-${{ github.run_id }}"
          git checkout -b "$branch"
          git add .
          git diff --staged --quiet && exit 0
          git commit -m "feat: update translations"
          git push origin "$branch"
          gh pr create --fill --base "${{ github.ref_name }}" --head "$branch"

Enable Settings > Actions > General > Allow GitHub Actions to create and approve pull requests for PR-based workflows.

The same job works on feature branches - change the on.push.branches filter (for example branches-ignore: [main]) to control where localization runs.

Next Steps#

GitHub App

Managed alternative - no runner, secret, or lockfile

CLI reference

Commands, configuration, and CI usage

Advanced Patterns

Localization checks, merge conflicts, workflow selection

GitLab CI/CD

Set up GitLab CI/CD integration