Set up continuous localization on GitHub, GitLab, or Bitbucket. There are two supported paths: the managed Lingo.dev GitHub App, and running @lingo.dev/cli in your own pipeline. Pick the one that fits your platform and how much control you want.
Which path should I use?#
| Path | Best for | What it needs |
|---|---|---|
| GitHub App | Repositories hosted on GitHub | Install the app, commit .lingo/config.json with an engineId. No runner, secret, or CLI. |
@lingo.dev/cli in a runner | GitLab, Bitbucket, or GitHub Actions if you want full control | Node 22+, @lingo.dev/cli, a LINGO_API_KEY secret, and a job that runs lingo push. |
On GitHub? Start with the GitHub App
The GitHub App runs server-side. It reads a committed .lingo/config.json (including your engineId), reacts to pushes and pull requests, and needs no runner, API key secret, or lock file. Follow the GitHub App guide and you're done - the rest of this page covers running the CLI in your own pipeline.
Running the CLI in your pipeline#
If you're on GitLab or Bitbucket, or you want to drive localization yourself on GitHub, run @lingo.dev/cli as a job in your pipeline. The setup is the same three steps on every platform: configure the CLI, add your API key, and choose a workflow.
Prerequisites
You need a working CLI setup with a .lingo/config.json file and the ability to run lingo push locally before adding it to CI.
Step 1. Configure the CLI#
If you haven't already, follow the CLI Quickstart. You should end up with:
- A
.lingo/config.jsonfile in your project root (see Configuration) - A
LINGO_API_KEYfor the Lingo.dev Engine - The ability to generate translations locally with
lingo push
The CLI runs on Node 22+. Install it in your pipeline with:
npm install -g @lingo.dev/cliStep 2. Add your API key as a CI secret#
lingo push authenticates with the LINGO_API_KEY environment variable. Store it in your CI platform's secret management:
- Navigate to Settings > Secrets and variables > Actions
- Click New repository secret
- Name:
LINGO_API_KEY, Value: your API key - Click Add secret
Step 3. Choose a workflow and add the config#
Your job runs lingo push to generate translations, then commits the result or opens a pull request using your platform's own tooling. Pick the workflow that fits your team:
| Workflow | Best for |
|---|---|
| Commit to main | Small teams that want zero-friction, invisible translation updates |
| PR from main | Teams that want to review translations before they land on main |
| Commit to feature branch | Teams with long-lived feature branches |
| PR from feature branch | Teams that want maximum control over every translation change |
Not sure which to pick? Start with "Commit to main" - it's the simplest. You can switch later without changing your .lingo/config.json.
For platform-specific setup instructions and workflow examples, see:
Verify the setup#
After configuring your CI job, push a change to trigger it. The pipeline should:
- Run
lingo pushto translate new and changed content - Commit translations or open a PR (depending on your workflow)
- Update the
.lingo/lock.jsonfile, which tracks what has already been translated
To verify translations are complete in CI without generating new ones, run lingo check:
lingo checkThis exits with a non-zero status if any content is untranslated - useful as a deployment gate. See Advanced Patterns for examples.
