Lingo.dev keeps translations in sync with your code. On every change, it detects what content changed, translates it using your connected localization engine - with glossary rules, brand voice, and per-locale model configuration applied consistently - and commits the results or opens a pull request. Incomplete translations never reach production.
Choose your integration#
Each integration has its own guide. Pick the one that matches your setup:
| Integration | How it runs |
|---|---|
| GitHub App | Install once. Lingo.dev runs localization for you on pushes to the default branch, and on pull requests when enabled - no runner, no API key secret, no lockfile. |
| GitHub Actions | Installs @lingo.dev/cli and runs lingo push in your GitHub Actions pipeline, then commits results or opens a PR. |
| GitLab CI/CD | Installs @lingo.dev/cli and runs lingo push in a GitLab pipeline job. |
| Bitbucket Pipelines | Installs @lingo.dev/cli and runs lingo push in a Bitbucket pipeline step. |
The GitHub App runs on Lingo.dev's servers. Every other integration runs the Lingo.dev CLI - so any CI/CD environment with Node.js 22+ can run localization directly, even without a first-party integration.
How the GitHub App works#
Install the app once and add a .lingo/config.json to the repository. From then on, Lingo.dev runs localization for you - no pipeline, no API key secret, no lockfile:
- Watches for changes - reacts to pushes on the default branch out of the box, and to pull requests once you enable
onPullRequest, checking changed files against the source patterns you configure - Translates the delta - sends changed source content through the engine named by
engineId - Writes results back to GitHub - on default-branch pushes it opens or updates a translation pull request; on pull requests it commits translated files to the PR branch and posts a status comment
- Recovers and batches - detects changes missed by an earlier run and splits very large updates across multiple commits
You can gate runs behind an approval step or trigger translations manually with /lingo commands in a pull request. See the GitHub App guide for the full configuration.
How the CLI integrations work#
The GitHub Actions, GitLab CI/CD, and Bitbucket integrations all run the same Lingo.dev CLI as a step in your existing pipeline. They need two things: your .lingo/config.json configuration and a LINGO_API_KEY for authentication.
On each run, the job installs the CLI (npm install -g @lingo.dev/cli) and runs lingo push, which:
- Discovers source files - reads your bucket configuration to find translatable content
- Detects changes - compares against the
.lingo/lock.jsonlockfile to identify new or modified strings, so only the delta gets translated - Translates - sends changed content through your configured localization engine with all rules applied - glossary, brand voice, per-locale model settings
- Writes results - updates target locale files in place and refreshes
.lingo/lock.json
Your pipeline then commits the results or opens a pull request with your platform's own tooling. Because only changed strings are translated, runs are fast and cost-efficient - even across dozens of locales.
Workflow options#
GitHub App#
The App's behavior is configured in .lingo/config.json:
| Option | What it does |
|---|---|
Push to default branch (onPushToDefaultBranch) | Enabled by default. Opens or updates a translation PR when source changes land on the default branch. |
Pull request translation (onPullRequest) | Disabled by default. Commits translations to the PR branch as the PR changes. |
Approval gate (requireApproval) | Disabled by default. Requires Approve/Deny on the check run, or /lingo approve on a PR, before automatic runs translate. |
Manual commands (/lingo translate) | Backfill or force translations for specific files from a PR comment, any time. |
See the GitHub App guide for full config and command reference.
CLI in CI/CD (GitHub Actions, GitLab CI, Bitbucket)#
Four workflow patterns cover most team setups:
| Workflow | Trigger | Output |
|---|---|---|
| Commit to main | Push to main | Translations committed directly to main |
| PR from main | Push to main | Pull request with translations |
| Commit to feature branch | Push to feature branch | Translations committed to the branch |
| PR from feature branch | Push to feature branch | Pull request from the branch |
The first option - commit to main - is the simplest. Translations appear automatically with zero developer intervention. The PR-based options add a review step before translations land.
For details on choosing between these, see Advanced Patterns.
